How do you use Kustomize overlays in a GitOps repository?

Kustomize is a template-free Kubernetes manifest customisation tool built into kubectl and natively supported by both Argo CD and Flux. The overlay pattern keeps shared resource definitions in a base/ directory and accumulates environment-specific differences in per-environment overlays/ directories, avoiding duplication while keeping diffs small and reviewable.

A base kustomization.yaml simply lists the resources it manages:

# apps/my-app/base/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - deployment.yaml
  - service.yaml
  - hpa.yaml

A production overlay then references the base and applies patches:

# apps/my-app/overlays/prod/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - ../../base
namePrefix: prod-
commonLabels:
  env: production
images:
  - name: my-app
    newName: registry.example.com/my-app
    newTag: v2.1.0
patches:
  # Strategic merge patch: increase replicas for prod
  - path: replica-patch.yaml
  # JSON 6902 patch: set a specific env var
  - patch: |-
      - op: replace
        path: /spec/template/spec/containers/0/env/0/value
        value: "production"
    target:
      kind: Deployment
      name: my-app

Useful Kustomize fields in overlays: namePrefix / nameSuffix to namespace resource names per environment; commonLabels / commonAnnotations to tag all resources; configMapGenerator and secretGenerator to create environment-specific ConfigMaps or Secrets. Argo CD and Flux both run kustomize build on these directories before applying, so the raw YAML you store in Git is never the final manifest — patches are applied at sync time.