Create a Staging Overlay with Kustomize

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

Kustomize overlays: change an environment without touching the base

A base is a directory with a kustomization.yaml listing shared manifests. An overlay is another directory whose kustomization.yaml pulls the base in as a resource and layers changes on top. The base never learns about its overlays, so dev, QA and prod can share one copy of the manifests. The exam habit that matters most: render with kubectl kustomize and read the output before you apply anything.

prepium-kz/
  base/          kustomization.yaml, deployment.yaml     (shared, unchanged)
  overlays/qa/   kustomization.yaml, cpu-request.yaml    (QA differences only)

1. A base with a generated ConfigMap

base/deployment.yaml is an ordinary Deployment named notes (one replica, container web, image nginx:1.27-alpine) whose container loads envFrom a ConfigMap called notes-settings. The base kustomization generates that ConfigMap:

# base/kustomization.yaml
resources:
- deployment.yaml
configMapGenerator:
- name: notes-settings
  literals:
  - GREETING=hello

Run kubectl kustomize base. The ConfigMap comes out as notes-settings- plus a hash of its contents, and the Deployment's configMapRef has been rewritten to that exact name. Change the literal and the hash changes, so the Pod template changes and a new rollout starts: config edits can no longer go unnoticed by running Pods.

2. An overlay that changes only what differs

# overlays/qa/kustomization.yaml
resources:
- ../../base
namespace: prepium-tutorial
namePrefix: qa-
labels:
- pairs:
    tier: qa
replicas:
- name: notes
  count: 2
configMapGenerator:
- name: notes-settings
  behavior: merge
  literals:
  - GREETING=hola
patches:
- path: cpu-request.yaml

cpu-request.yaml is a partial Deployment: apiVersion, kind, metadata.name: notes, then just spec.template.spec.containers with name: web and a resources.requests.cpu value. Strategic merge matches containers by name, so only that field is added.

3. Read the rendered result

kubectl kustomize overlays/qa

What to look for:

• Names become qa-notes and qa-notes-settings-<hash>, and the reference inside the Pod template follows both changes.
• Every object carries namespace: prepium-tutorial.
• tier: qa appears in each object's metadata.labels, but not on the Pod template or selector. The labels field leaves those alone unless you set includeTemplates: true (Pods only) or includeSelectors: true (selectors too).
• replicas: 2, the merged GREETING=hola, and the CPU request.

Images work the same way: an images list can swap a name, tag or digest without writing a patch.

4. Apply and confirm

kubectl create namespace prepium-tutorial
kubectl apply -k overlays/qa
kubectl -n prepium-tutorial get deploy,cm --show-labels

Common mistakes

• A patch whose container name does not match. Kustomize does not complain; it appends a second, image-less container. The preview shows two entries under containers.
• Adding labels with includeSelectors: true (or the deprecated commonLabels) to a Deployment that is already running. Its selector is immutable, so the apply is rejected.
• Expecting kubectl get pods -l tier=qa to match when only pairs were set. Without includeTemplates, Pods never receive the label.
• Using apply -f on the overlay directory. Only -k runs Kustomize; -f treats the files as plain manifests.

Cleanup: kubectl delete -k overlays/qa and kubectl delete namespace prepium-tutorial. References: Declarative management using Kustomize, labels, patches, configMapGenerator. Next, try Helm releases.