Build a Production Kustomize Overlay Without Editing the Base

Original Prepium guide · Written for Kubernetes v1.35 and checked against the official documentation on 6 October 2026. Use a disposable practice cluster. Everything below uses the Kustomize built into kubectl, so no extra binary is needed.

Kustomize bases and overlays: change an app per environment without touching the original YAML

Kustomize builds manifests from a kustomization.yaml. A base is a directory of plain resources that knows nothing about environments. An overlay is another kustomization that lists the base under resources and layers changes on top: a namespace, image tags, replica counts, patches. Because the base is never edited, several overlays can share it, and you can always rebuild exactly what was deployed.

ledger/
├── base/                 deployment.yaml + kustomization.yaml (resources only)
└── overlays/staging/     kustomization.yaml ──resources: ../../base
                          + namespace + images + replicas + patches ──→ kubectl kustomize / apply -k

1. Know which Kustomize you are running

kubectl version --client

The client output includes a Kustomize Version line. kubectl embeds its own copy, and that copy has moved over time (frozen at v2.0.3 until kubectl v1.21, v5 from kubectl v1.27), so check it before trusting a blog post. In current versions bases: is deprecated in favour of listing directories under resources:, and patchesStrategicMerge/patchesJson6902 are deprecated in favour of a single patches: list. The kubectl kustomize command also exposes flags such as --enable-helm, which you rarely need on the exam.

2. A base that stays generic

ledger/base/kustomization.yaml only lists files:

resources:
- deployment.yaml

Its deployment.yaml is an ordinary Deployment named ledger-api with one replica and a container image httpd:2.4, and no namespace set.

3. An overlay that changes four things

ledger/overlays/staging/kustomization.yaml:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- ../../base
namespace: prepium-tutorial
images:
- name: httpd
  newTag: 2.4-alpine
replicas:
- name: ledger-api
  count: 2
patches:
- path: memory-limit.yaml

Each field is a transformer with one job. namespace sets or overrides the namespace on every resource. images matches containers by image name and swaps the tag (or the name, with newName) without a patch. replicas matches by resource name and works for Deployments, ReplicaSets, ReplicationControllers and StatefulSets. patches handles anything else; here memory-limit.yaml is a small strategic-merge patch that names the Deployment and its container and adds a memory limit. The docs recommend small patches that do one thing each.

4. Render, compare, apply, verify

kubectl create namespace prepium-tutorial
kubectl kustomize ledger/overlays/staging          # print only, change nothing
kubectl diff -k ledger/overlays/staging            # compare with the live cluster
kubectl apply -k ledger/overlays/staging
kubectl -n prepium-tutorial rollout status deployment/ledger-api
kubectl -n prepium-tutorial get deploy ledger-api -o jsonpath='{.spec.replicas} {.spec.template.spec.containers[0].image}'

-k must point at a directory that contains a kustomization file. Rendering the base on its own (kubectl kustomize ledger/base) should still show one replica and the original tag: that proves the overlay did the work.

Common mistakes

• Listing a base file such as ../../base/deployment.yaml instead of the base directory: the default load restrictor refuses files outside the overlay's root, so reference the directory.
• Putting the registry or tag into images[].name: the name must match the image name as written in the base, without its tag.
• Editing the base to get the overlay working: other overlays inherit the change, which is exactly what bases are meant to prevent.
• Pointing kubectl apply -f at the overlay folder: -f takes plain manifest files and does not run Kustomize. Use -k, which cannot be combined with -f.

Cleanup: kubectl delete -k ledger/overlays/staging, then kubectl delete namespace prepium-tutorial. References: Declarative Management of Kubernetes Objects Using Kustomize, Kustomization reference, kubectl kustomize. Next, try Kustomize for CKAD or rendering a Helm chart.