How to Use Kustomize Overlays Per Environment

A Kustomize base holds shared manifests and each overlay patches the differences, so staging and production share one source with small deltas.

Put common manifests in base/ and create overlays that reference the base and apply patches. Each overlay sets its own image tag, replica count, and namespace.

Steps

• Put shared manifests under base/ with a kustomization.yaml.
• Create overlays/<env>/kustomization.yaml with resources: [../../base].
• Patch env-specific values (replicas, tag, config).
• Point each Argo CD app or Flux Kustomization at an overlay path.

Production overlay

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - ../../base
namespace: api
images:
  - name: ghcr.io/my-org/api
    newTag: v1.4.2
replicas:
  - name: api
    count: 4
patches:
  - path: resources-patch.yaml
    target:
      kind: Deployment
      name: api

Gotchas

• Keep environment differences small; large overlays signal the base is wrong.
• Validate a rendered overlay with kustomize build overlays/production before committing.

Related guides