Differentiate Environments with Kustomize

Why this matters

Three copied manifest trees rot at different speeds: the staging fix that never reaches production, the production secret that leaks into the staging repo. Overlays express environments as patches on one base, so the common shape has exactly one author and each environment declares only its differences.

Concepts

A base holds the shared manifests plus a kustomization.yaml listing resources. An overlay references the base and adds patches: name prefixes or suffixes per environment, replica counts, image tags, strategic-merge or JSON patches for surgical edits. kubectl apply -k <overlay-dir> builds then applies; kubectl kustomize <overlay-dir> (or kustomize build) renders the final manifests for reading and diffing without touching the cluster.

ConfigMap and Secret generators deserve special attention: instead of hand-writing data files, the overlay generates them from literal values or env files, with content-hash suffixes that roll dependents automatically when data changes. Common labels and annotations across an overlay keep selectors and ownership consistent.

Worked example

One deployment base, staging with two replicas plus debug label, production with five:

base/
  deployment.yaml        # replicas: 1, image: shop:3.2
  kustomization.yaml     # resources: [deployment.yaml]
overlays/staging/kustomization.yaml:
  resources: [../../base]
  namePrefix: staging-
  replicas: [{ name: shop, count: 2 }]
  commonLabels: { env: staging }
overlays/prod/kustomization.yaml:
  resources: [../../base]
  namePrefix: prod-
  replicas: [{ name: shop, count: 5 }]
  commonLabels: { env: prod }

kubectl kustomize overlays/staging shows the built staging manifests for inspection; kubectl diff -k overlays/staging previews against the cluster; kubectl apply -k overlays/prod ships production. Same base, two honest differences, zero copies.

Exam notes

Paths in kustomization.yaml are relative to the file, not your shell: run from anywhere but write paths from the kustomization. Name prefixes rename everything including selectors consistently, which is why cross-references keep working. And always build or diff before apply: the overlay you imagined and the manifests generated are two different things until rendered.