Bases & overlays

dev, staging, prod from one base.

The bases-and-overlays structure is Kustomize’s reason to exist. A base directory holds the shared manifests and a kustomization.yaml. Each overlay is its own directory whose kustomization.yaml references the base under resources (or the newer components) and then patches it. The base knows nothing about environments; the overlays hold every environment-specific difference, so shared config lives in exactly one place.

base/
  kustomization.yaml        # resources: deployment.yaml, service.yaml
  deployment.yaml
  service.yaml
overlays/
  dev/kustomization.yaml     # resources: ../../base ; patches: 1 replica
  prod/kustomization.yaml    # resources: ../../base ; patches: 4 replicas, prod image

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - ../../base
namespace: payments-prod
replicas:
  - name: payments-api
    count: 4
images:
  - name: payments-api
    newTag: "2.1.0"

One base, many environments

Now a change to the shared shape (add a liveness probe, tighten a securityContext) is made once in the base and every environment inherits it, while environment differences (scale, image, namespace) stay isolated in their overlays. This is the same benefit as a Helm chart with per-env values, achieved with plain YAML and patches. Overlays can even stack — a team overlay on a region base on a common base — for larger organizations.