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.

Invest now in Acorns!!! 🚀
Join Acorns and get your $5 bonus!

Acorns is a micro-investing app that automatically invests your "spare change" from daily purchases into diversified, expert-built portfolios of ETFs. It is designed for beginners, allowing you to start investing with as little as $5. The service automates saving and investing. Disclosure: I may receive a referral bonus.

Invest now!!! Get Free equity stock (US, UK only)!

Use Robinhood app to invest in stocks. It is safe and secure. Use the Referral link to claim your free stock when you sign up!.

The Robinhood app makes it easy to trade stocks, crypto and more.

Webull! Receive free stock by signing up using the link: Webull signup.