Learning GitOps - FluxCD - Variable Substitution & Configuration

#Introduction

In episode 10 you learned to control the deploy order. One problem remains: how do we keep a single set of manifests valid for many clusters and environments, without rewriting YAML? The answer is variable substitution.

This episode covers Flux variable syntax, postBuild with substitute and substituteFrom, configuration strategies, secret management integration, and its best practices.

#Variable Substitution

Flux provides variables that can be used inside rendered manifests. The syntax: a dollar sign, then the variable name between curly braces. Variable values are defined through the postBuild block on the Kustomization. Example usage in a manifest:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: webapp
  namespace: webapp
spec:
  replicas: ${replica_count}
  template:
    spec:
      containers:
        - name: webapp
          image: registry.internal.acme.com/webapp:${image_tag}
          env:
            - name: CLUSTER
              value: ${cluster_name}

The variable value sources:

There are also built-in variables available automatically: CLUSTER_NAME contains the cluster name from the clusters/ directory used at bootstrap, plus other values you set during flux bootstrap --cluster-domain or in the substitute block.

#Post-Build Variable Substitution

Variable replacement is enabled through the postBuild block on the Kustomization:

apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: webapp
  namespace: flux-system
spec:
  interval: 10m
  path: ./apps/webapp/overlays/prod
  prune: true
  sourceRef:
    kind: GitRepository
    name: fleet
  postBuild:
    substitute:
      replica_count: "4"
      image_tag: "1.2.0"
      cluster_name: "prod-eks-a"
    substituteFrom:
      - kind: ConfigMap
        name: platform-vars
      - kind: Secret
        name: app-secrets

How postBuild works:

1. Kustomize renders the manifests (merge, patch, generator).
2. Variables from substitute are replaced first.
3. Variables from substituteFrom are replaced following the order of the list.
4. The final result is applied to the cluster.

#Testing Substitution with Kubectl

While writing files, you can test the substitution result without a cluster using kubectl kustomize:

kubectl kustomize ./apps/webapp/overlays/prod

And to check the final result after Flux applies it:

kubectl get deployment webapp -n webapp -o yaml | grep replicas

#Configuration Strategies

Variables give freedom, but they need discipline. Four common strategies:

#Environment-Specific

One overlays per environment (dev, staging, prod), each with its own substitute. This continues the overlays pattern from episode 7 — variables add flexibility without adding files.

#Multi-Cluster

Use the same Kustomization for all clusters, differentiate values through a per-cluster platform-vars ConfigMap:

apiVersion: v1
kind: ConfigMap
metadata:
  name: platform-vars
  namespace: flux-system
data:
  region: ap-southeast-1
  domain: cluster-a.internal.acme.com

Different clusters simply choose different values in their own substitute or ConfigMap.

#Tenant-Specific

For multi-tenancy, per-tenant variables are stored in the tenant namespace, and the tenant Kustomization uses substituteFrom with the ConfigMap in its namespace. Tenancy details are covered in episode 12.

#Feature Flags

Variables can also serve as flags: a true or false value to enable a feature. Set the default value in base, then override it in specific overlays.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: webapp
  namespace: webapp
spec:
  template:
    spec:
      containers:
        - name: webapp
          env:
            - name: NEW_PAYMENT
              value: ${enable_new_payment}

#Secret Management Integration

Variables aren't for real secrets. For that, Flux works together with the secret management ecosystem:

Example of a Flux Kustomization with SOPS decryption:

apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: webapp
  namespace: flux-system
spec:
  interval: 10m
  path: ./apps/webapp/overlays/prod
  prune: true
  sourceRef:
    kind: GitRepository
    name: fleet
  decryption:
    provider: sops
    secretRef:
      name: sops-age

#Best Practices

• Minimal duplication — put shared values in one place, let overlays only override the delta.
• Clear naming — use descriptive snake_case like image_tag, replica_count, ingress_domain; avoid generic names like value1.
• Documentation — create a variable list per overlay, for example in a README.md or as comments in kustomization.yaml, so it's easy to track.
• Validation — check for unsubstituted placeholders before deploying; Flux reports undefined variables as a reconciliation error.

flux get kustomizations
kubectl get deployment webapp -n webapp -o jsonpath='{.spec.replicas}'

#Closing

Configuration is now flexible without becoming messy:

• Variable syntax separates values from manifest structure.
• postBuild with substitute and substituteFrom manages value sources declaratively.
• Environment-specific, multi-cluster, tenant, and feature flag strategies cover almost every need.
• SOPS, Sealed Secrets, External Secrets Operator, and Vault keep secrets safe.
• Best practices keep the repository readable and auditable.

You now have a complete foundation for single-cluster GitOps. In episode 12 we'll implement multi-tenancy with Flux: the tenancy model, flux create tenant, namespace isolation, and per-tenant service accounts. See you!