Kustomize Patterns

Purpose: For platform engineers, provides Kustomize base/overlay composition, merge patches, and variable substitution patterns.

Pattern 1: Base + Overlay Composition

openCenter uses the Kustomize base/overlay pattern to separate shared service definitions from cluster-specific configuration.

openCenter-gitops-base/                    # Base (shared)
  applications/base/services/cert-manager/
    ├── namespace.yaml
    ├── source.yaml
    ├── helmrelease.yaml
    └── helm-values/hardened-values-v1.18.2.yaml

customer-repo/                             # Overlay (cluster-specific)
  applications/overlays/<cluster>/services/cert-manager/
    ├── kustomization.yaml
    └── override-values.yaml

The overlay's kustomization.yaml references the base via a FluxCD Kustomization CRD (not a native Kustomize resource). FluxCD fetches the base from a GitRepository source and applies the overlay on top.

Pattern 2: postBuild Variable Substitution

FluxCD Kustomizations support postBuild.substituteFrom, which replaces ${VARIABLE} placeholders in rendered manifests with values from ConfigMaps or Secrets.

apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: cert-manager-base
  namespace: flux-system
spec:
  postBuild:
    substituteFrom:
      - kind: ConfigMap
        name: cluster-vars

The cluster-vars ConfigMap holds cluster-specific values:

apiVersion: v1
kind: ConfigMap
metadata:
  name: cluster-vars
  namespace: flux-system
data:
  CLUSTER_NAME: "prod-cluster"
  CLUSTER_DOMAIN: "prod.example.com"
  METALLB_IP_RANGE: "192.168.12.100-192.168.12.120"

Base manifests reference these as ${CLUSTER_NAME}, ${CLUSTER_DOMAIN}, etc. Substitution happens after Kustomize rendering but before applying to the cluster.

Pattern 3: Kustomize Components

Components are reusable Kustomize fragments that can be included in multiple overlays. openCenter uses components for optional features like Istio mTLS or Windows node taints.

# kustomization.yaml in an overlay
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
components:
  - ../../components/istio-mtls
  - ../../components/windows-tolerations

Components differ from bases: a base is included once via resources, while a component can add patches, transformers, or generators to any overlay that includes it.

Pattern 4: Strategic Merge Patches

Used in overlays to modify specific fields in base resources without replacing the entire manifest:

# kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
patches:
  - target:
      kind: HelmRelease
      name: cert-manager
    patch: |
      - op: replace
        path: /spec/chart/spec/version
        value: "v1.17.0"

Pattern 5: ConfigMap Generators

Overlays generate ConfigMaps from override values files, which are then consumed by HelmRelease resources via valuesFrom:

# kustomization.yaml
configMapGenerator:
  - name: cert-manager-override-values
    namespace: cert-manager
    files:
      - values.yaml=override-values.yaml
generatorOptions:
  disableNameSuffixHash: true

When to Use Each Pattern

Pattern	Use case
Base + Overlay	Standard service deployment with cluster overrides
postBuild substitution	Injecting cluster-wide variables (IPs, domains)
Components	Optional features shared across overlays
Strategic merge patches	Targeted field changes in base resources
ConfigMap generators	Helm values overrides from files

Pattern 1: Base + Overlay Composition​

Pattern 2: postBuild Variable Substitution​

Pattern 3: Kustomize Components​

Pattern 4: Strategic Merge Patches​

Pattern 5: ConfigMap Generators​

When to Use Each Pattern​