Kustomize
Topic 42

Kustomize

ConfigOverlays

Kustomize manages Kubernetes configuration without templates. You keep a base of plain manifests and apply overlays that patch them for each environment. There is no templating language — overlays are themselves valid YAML — and it is built into kubectl.

Where Helm parameterizes with values and templating, Kustomize composes with bases and patches. The two are the dominant approaches to the same problem, and the choice between them is a recurring decision.

Bases and Overlays

A base is a directory of complete, valid manifests plus a kustomization.yaml listing them. An overlay references a base and layers changes on top — a dev overlay and a prod overlay can share one base and differ only in replica count, image tag, and resources. Because every layer is real YAML, you can read and validate it directly, with no rendering step to reason about.

A prod overlay patching a shared base
# overlays/prod/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - ../../base
replicas:
  - name: web
    count: 5
images:
  - name: my-app
    newTag: "2.0"
patches:
  - path: resources-patch.yaml

Patches and Transformers

Overlays change the base in a few ways. Strategic-merge patches overlay a partial manifest onto a matching resource; JSON 6902 patches make precise operations (replace this field, add this list item). Built-in transformers handle common needs — set a common label or name prefix across everything, change image tags, adjust replica counts — without writing a patch at all. The model is composition, not substitution.

Generators

Kustomize can generate ConfigMaps and Secrets from files or literals, and it appends a content hash to their names so that changing the data produces a new name — which automatically triggers a rolling update of the Deployments that reference them. This neatly solves the "I changed a ConfigMap but nothing rolled" problem from Topic 10. The same caution applies, though: secret generators put data into the build output, so secrets still need a real store, not plaintext in Git.

When Kustomize Fits

Kustomize shines when you manage your own applications across environments and value readability and no templating. Helm shines when you distribute configurable software to others or need release lifecycle and packaging. They are not exclusive — you can render a Helm chart and patch it with Kustomize — but for most in-house app config, the simplicity of bases and overlays is a feature. What Kustomize deliberately lacks is loops and conditionals; if you need those, that is a signal you may want Helm.

Kustomize vs Helm

Kustomize — no templating — bases and overlays of plain YAML, built into kubectl. Best for in-house app config and readability.

Helm — templating, packaging, and release lifecycle. Best for distributing configurable software and when you need logic.

Common Mistakes
  • Building deep overlay-on-overlay hierarchies until the effective config is hard to follow.
  • Using secret generators with plaintext data committed to Git.
  • Expecting loops or conditionals — Kustomize is composition, not a templating language.
  • Mixing Helm and Kustomize haphazardly so it's unclear which produced the final manifest.
  • Reinventing per-environment copies by hand instead of using one base with overlays.
Best Practices
  • Keep a single base and thin per-environment overlays; avoid deep inheritance.
  • Use generators with content-hash names so config changes trigger rollouts automatically.
  • Keep secret data in a real store, not in committed generator inputs.
  • Choose Kustomize for in-house app config; choose Helm when you need packaging or logic.
  • Validate the built output (kustomize build / kubectl kustomize) before applying.
RelatedHelm — the templating/packaging alternative (Topic 41)ConfigMaps and Secrets — generators trigger rollouts on change (Topic 10)GitOps — Argo CD and Flux render both natively (Topic 43)

Knowledge Check

How does Kustomize differ fundamentally from Helm?

  • It uses no templating — plain-YAML bases plus overlays, composed with patches
  • It packages versioned charts and distributes them through a chart registry
  • It tracks per-release revision history for rollback
  • It requires an in-cluster controller to run its builds

How do Kustomize ConfigMap/Secret generators trigger a rollout on change?

  • They append a hash to the name, so changed data renames the object and the Deployment rolls
  • They restart the kubelet on each node so it reloads the changed data
  • They inject a restart timestamp annotation into the Deployment's pod template on each build
  • They cannot trigger a rollout when the config data changes

Needing loops and conditionals in your config is a signal to consider what?

  • Helm — Kustomize is composition only and deliberately omits templating logic
  • Writing a custom controller to reconcile the generated configuration at runtime
  • Adding an aggregated API server to the cluster
  • Switching to bare kubectl apply with no overlays

You got correct