Manage dev, staging and prod with Kustomize overlays

Approach

Keep shared manifests in a base and put only real differences in overlays: namespace, image tag, replicas and a few patches. Render every overlay in CI.

Solution

# overlays/prod/kustomization.yaml
resources: [../../base]
namespace: prod
images:
  - name: ghcr.io/acme/api
    newTag: 1.4.2
replicas:
  - name: api
    count: 4
patches:
  - target: {kind: Deployment, name: api}
    patch: |
      - op: add
        path: /spec/template/spec/containers/0/env/-
        value: {name: REGION, value: eu-west-1}

kubectl kustomize overlays/prod | kubeconform -strict -summary -

Pitfalls

• JSON patch replace on lists, which drops existing items; use add with /- or a strategic merge patch.
• Overlays growing into near-copies; move shared changes to the base.

Variations

• Components for optional features shared by some overlays.
• Helm charts rendered through Kustomize (helmCharts) when you consume third-party charts.

Further reading: Kustomize