Kustomize, and Helm vs Kustomize¶
Status: AI draft, 2026-11-16. Not yet verified by me. The Kustomize commands were run with the Kustomize built into kubectl 1.37 (Kustomize 5.8) and a server dry run on a local kind cluster; the Helm side is from the documentation.
In one line¶
Kustomize customises plain YAML without templates: a base holds normal manifests, and each overlay lists changes (namespace, name prefix, image tags, replica counts, generated ConfigMaps, patches) that kubectl kustomize applies to produce the final YAML. Helm templates and packages; Kustomize patches; many teams use Helm for third-party apps and Kustomize for their own, or both together.
The plain idea¶
Helm says: write the YAML with holes in it, and fill the holes per environment (Charts, templates and values). Kustomize says: write ordinary, valid YAML once, and describe each environment as a set of edits on top of it. Nothing in the base is a placeholder; you can kubectl apply the base as it is.
It is built into kubectl (kubectl kustomize, kubectl apply -k), so there is nothing to install.
How it works¶
Base and overlays¶
flowchart TD
B["base/: deployment.yaml, service.yaml,<br/>kustomization.yaml"] --> D["overlays/dev/kustomization.yaml:<br/>namespace team-a-dev, image tag 1.5.0-rc1"]
B --> P["overlays/prod/kustomization.yaml:<br/>namespace team-a, prefix prod-,<br/>3 replicas, tag 1.4.2, CPU patch"]
D --> DY["kubectl kustomize overlays/dev"]
P --> PY["kubectl kustomize overlays/prod"]
kustomize-demo/
├── base/
│ ├── deployment.yaml
│ ├── service.yaml
│ └── kustomization.yaml
└── overlays/
├── dev/kustomization.yaml
└── prod/kustomization.yaml
kustomization.yaml fields¶
| Field | What it does |
|---|---|
resources |
Files, directories or other kustomizations (a base) to include |
namespace |
Set the namespace on every object |
namePrefix, nameSuffix |
Rename every object, and update references to them |
labels |
Add labels; with includeSelectors: true also to selectors. Replaces the deprecated commonLabels, which always changed selectors |
commonAnnotations |
Add annotations to every object |
images |
Change image names, tags or digests without touching the Deployment |
replicas |
Change replica counts by object name |
configMapGenerator, secretGenerator |
Generate ConfigMaps or Secrets from literals or files, with a content hash in the name |
patches |
Strategic merge patches or JSON 6902 patches, optionally targeted by kind, name or label |
components |
Reusable groups of changes that several overlays can include |
helmCharts |
Render a Helm chart inside Kustomize (needs the Helm binary and --enable-helm) |
Generated ConfigMaps roll the pods¶
configMapGenerator appends a hash of the content to the name (sample-app-config-dfk4bdbtkk) and rewrites every reference to it. When the content changes, the name changes, the Deployment's pod template changes, and the pods roll. This solves "I changed the ConfigMap but the pods still use the old values" (ConfigMaps and Secrets).
A concrete example¶
The prod overlay used for the output below:
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namespace: team-a
namePrefix: prod-
resources:
- ../../base
images:
- name: registry.example.com/sample-app
newTag: 1.4.2
replicas:
- name: sample-app
count: 3
configMapGenerator:
- name: sample-app-config
behavior: merge
literals:
- LOG_LEVEL=warn
patches:
- target:
kind: Deployment
name: sample-app
patch: |-
- op: replace
path: /spec/template/spec/containers/0/resources/requests/cpu
value: 500m
The base Deployment has replicas: 1, image tag 1.0.0, CPU request 100m, and uses a ConfigMap from a generator with LOG_LEVEL=info; the base also adds the label app.kubernetes.io/part-of: sample-app with labels.
Why not just...?¶
- ...use Helm for everything? For your own services, a template language over YAML adds indirection: you read the template, the values and the helpers to know what will be applied. Kustomize keeps every file valid YAML. For third-party software published as charts, Helm is the natural choice.
- ...use Kustomize for everything? It has no packaging, versioning, release history, rollback or hooks, and complex conditional logic ("add this sidecar only if...") is awkward as patches. Helm or a GitOps controller fills those gaps.
- ...patch with
sedin CI? Text substitution does not understand YAML structure, breaks on formatting changes, and is invisible in review. Kustomize'simagesandpatchesare explicit and checked.
Commands to know¶
The prod overlay rendered, with the Kustomize built into kubectl:
$ kubectl kustomize overlays/prod
apiVersion: v1
data:
LOG_LEVEL: warn
kind: ConfigMap
metadata:
labels:
app.kubernetes.io/part-of: sample-app
name: prod-sample-app-config-dfk4bdbtkk
namespace: team-a
---
apiVersion: v1
kind: Service
metadata:
labels:
app.kubernetes.io/part-of: sample-app
name: prod-sample-app
namespace: team-a
spec:
ports:
- port: 80
targetPort: 8080
selector:
app: sample-app
---
apiVersion: apps/v1
kind: Deployment
metadata:
labels:
app.kubernetes.io/part-of: sample-app
name: prod-sample-app
namespace: team-a
spec:
replicas: 3
selector:
matchLabels:
app: sample-app
template:
metadata:
labels:
app: sample-app
spec:
containers:
- envFrom:
- configMapRef:
name: prod-sample-app-config-dfk4bdbtkk
image: registry.example.com/sample-app:1.4.2
name: app
resources:
requests:
cpu: 500m
memory: 128Mi
Every change is visible: the namespace and prod- prefix on all three objects, the reference to the renamed ConfigMap updated, the tag, the replica count and the patched CPU. The labels field added the label to metadata only, not to the selector, so the selector stays stable.
The dev overlay sets a different namespace and tag; its ConfigMap keeps the base content and so a different name:
$ kubectl kustomize overlays/dev | grep -E 'namespace:|image:|name: sample-app-config'
name: sample-app-config-hf678c7m2b
namespace: team-a-dev
namespace: team-a-dev
namespace: team-a-dev
name: sample-app-config-hf678c7m2b
image: registry.example.com/sample-app:1.5.0-rc1
Applying, checked by the API server without changing anything:
$ kubectl apply -k overlays/prod --dry-run=server
configmap/prod-sample-app-config-dfk4bdbtkk created (server dry run)
service/prod-sample-app created (server dry run)
deployment.apps/prod-sample-app created (server dry run)
| Command | What it does |
|---|---|
kubectl kustomize <dir> |
Render to stdout. |
kubectl apply -k <dir> |
Render and apply. |
kubectl diff -k <dir> |
What would change in the cluster. |
kubectl delete -k <dir> |
Delete exactly the rendered objects; review the render first. |
kubectl kustomize <dir> --enable-helm |
Allow helmCharts (needs Helm installed). |
Helm vs Kustomize¶
| Helm | Kustomize | |
|---|---|---|
| Approach | Templates with values | Plain YAML plus patches |
| Files | Templates are not valid YAML until rendered | Every file is valid YAML |
| Packaging and versions | Charts, repositories, OCI registries | None; Git directories or remote bases |
| Release tracking, rollback | Yes | No (kubectl, or a GitOps tool) |
| Hooks, ordering | Hooks | None (GitOps sync waves can do it) |
| Conditionals and loops | Yes | Patches and components only |
| Installing | Separate binary | Built into kubectl |
| Best at | Distributing software with many options | Your own apps across a few environments |
Using both: render a vendor chart with Helm (or helmCharts), then patch the output with Kustomize for the things the chart does not expose. Argo CD supports both natively (Argo CD architecture).
How it breaks¶
| Symptom | Layer | Check | Likely cause |
|---|---|---|---|
| Patch has no effect | Targeting | target kind and name against the base |
Name matched after a prefix, or wrong kind; patches match original names |
no matches for Id ... |
Patch target | Rendered base | The object does not exist in the resources |
Selector changed, apply fails field is immutable |
Labels | commonLabels or includeSelectors |
Labels were added to selectors of an existing Deployment |
| Old ConfigMaps pile up | Generators | Hash-named ConfigMaps | Each change makes a new one; prune with your apply tool |
security; file ... is not in or below ... |
Load restrictor | Paths in resources |
Referring to files outside the kustomization root |
helmCharts ignored or error |
Helm support | Flags | --enable-helm not set, or Helm not installed |
Interview questions¶
1. What is the core idea of Kustomize?
Answer
- A base of plain, valid YAML and overlays that describe changes per environment.
- No templating: changes are declarative transformations and patches.
- Built into kubectl as
kubectl kustomizeandkubectl apply -k.
2. Why do generated ConfigMaps have a hash suffix?
Answer
- The name changes when the content changes, and references are updated.
- So the pod template changes and the Deployment rolls new pods with the new config.
- Without it, pods keep using old values until restarted.
3. When would you choose Helm and when Kustomize?
Answer
- Helm: distributing or consuming packaged software with many options, release history, hooks.
- Kustomize: your own services across environments, keeping YAML readable and diffable.
- Both: Helm for vendor charts, Kustomize patches on top.
4. Why is labels preferred over commonLabels?
Answer
commonLabels(deprecated) also adds labels to selectors.- Selectors of Deployments and Services cannot be changed once applied, so adding a label later breaks the apply.
labelsadds to metadata only unlessincludeSelectorsis set.
5. A patch in the prod overlay does nothing. How do you debug it?
Answer
- Render with
kubectl kustomizeand check the object. - Check the patch target's kind and original name, and the JSON path or merge structure.
- Render the base alone to see what the patch is applied to.
6. How do you change the image tag per environment with Kustomize?
Answer
- The
imagesfield in the overlay:nameof the image andnewTag(ordigest). - CI can set it with
kustomize edit set imageand commit the change for GitOps. - No edits to the base Deployment.
Try it¶
On any machine with kubectl:
- Recreate the base and the two overlays above in a scratch folder.
- Before rendering, predict the name of the prod ConfigMap's prefix and the Deployment's replica count; then run
kubectl kustomize overlays/prod. - Change
LOG_LEVELin the prod overlay toerrorand render again. Which names changed, and why does that matter for running pods? - Add
includeSelectors: trueunderlabelsin the base and render; compare the selector.
Zoom out¶
Kustomize and Helm are two answers to one question: how to keep one set of manifests for many environments. GitOps tools render either from Git and apply the result (GitOps principles), and promotion between environments becomes a change to an overlay or a values file (Promotion and rollback).