Kustomize Cheat Sheet
Kustomize declarative Kubernetes config management covering overlays, patches, generators, and common CLI commands.
Base kustomization.yaml
A minimal base referencing raw Kubernetes manifests.
apiVersion: kustomize.config.k8s.io/v1beta1kind: Kustomizationresources: - deployment.yaml - service.yaml - configmap.yamlcommonLabels: app.kubernetes.io/name: checkoutimages: - name: myapp newTag: 1.4.2
Overlay with Patches
Environment-specific overlay that patches the base for production.
# overlays/prod/kustomization.yamlapiVersion: kustomize.config.k8s.io/v1beta1kind: Kustomizationnamespace: prodresources: - ../../basepatches: - target: kind: Deployment name: checkout patch: |- - op: replace path: /spec/replicas value: 5configMapGenerator: - name: checkout-config behavior: merge literals: - LOG_LEVEL=warnreplicas: - name: checkout count: 5
CLI Commands
Building and applying kustomizations.
# Render final manifests without applyingkustomize build overlays/prod# Apply directly via kubectl (native kustomize support)kubectl apply -k overlays/prod# Diff against the live clusterkubectl diff -k overlays/prod# Add a resource to a kustomizationkustomize edit add resource deployment.yaml# Set an image tag programmaticallykustomize edit set image myapp=myapp:1.5.0
Generators & Transformers
Built-in fields for generating and transforming resources.
- configMapGenerator- generates a ConfigMap from literals or files, auto-appends a content hash suffix
- secretGenerator- generates a Secret the same way; combine with SOPS/sealed-secrets for encryption at rest
- namePrefix / nameSuffix- prepends/appends a string to all resource names in scope
- commonAnnotations- applies annotations across every resource in the kustomization
- patchesStrategicMerge (legacy) / patches- modern `patches` field supports both strategic-merge and JSON6902 patches
- components- reusable, optional bundles of config that overlays can opt into
JSON6902 Patch (Precise Ops)
Use RFC 6902 operations when a strategic-merge patch can't express what you need, like array element edits.
patches: - target: kind: Deployment name: checkout patch: |- - op: add path: /spec/template/spec/containers/0/env/- value: name: FEATURE_FLAG value: "true" - op: remove path: /spec/template/spec/containers/0/resources/limits/cpu - op: test path: /spec/replicas value: 3
Components: Optional Reusable Bundles
Components package a chunk of config (sidecar, extra resources) that overlays opt into independently of the base.
# components/istio-sidecar/kustomization.yamlapiVersion: kustomize.config.k8s.io/v1alpha1kind: Componentpatches: - target: kind: Deployment patch: |- - op: add path: /metadata/annotations/sidecar.istio.io~1inject value: "true"---# overlays/prod/kustomization.yamlresources: - ../../basecomponents: - ../../components/istio-sidecar
replacements: Cross-Resource Value Substitution
The modern replacement for the deprecated vars field — copies a value from one resource's field into another.
replacements: - source: kind: ConfigMap name: checkout-config fieldPath: data.API_HOST targets: - select: kind: Deployment name: checkout fieldPaths: - spec.template.spec.containers.[name=app].env.[name=API_HOST].value - source: kind: Service name: checkout fieldPath: metadata.name targets: - select: kind: Ingress fieldPaths: - spec.rules.0.http.paths.0.backend.service.name
Remote Bases via Git URL
Reference a base directly from a Git repo/tag without vendoring it locally.
resources: - github.com/org/platform-manifests/base/checkout?ref=v1.8.0# pin to a specific path + ref for reproducibilityresources: - https://github.com/org/platform-manifests//overlays/staging?ref=main
Transformer Ordering & Metadata Fields
Lesser-known fields that control build output shape and provenance.
- buildMetadata: [originAnnotations]- stamps each generated resource with the source file/repo it came from, useful for auditing
- sortOptions- controls whether output resources are sorted by kind (legacy) or left in declaration order
- patches ordering- patches apply strictly top-to-bottom in the list; later patches can undo earlier ones
- namePrefix/nameSuffix vs replacements- prefixes are purely textual; replacements can move typed values (ints, structured fields) between resources
- openapi.path- points Kustomize at a custom OpenAPI schema for validating CRD patches with strategic-merge semantics
- generatorOptions.disableNameSuffixHash- turns off the content-hash suffix on generated ConfigMaps/Secrets when you need a stable name
Let configMapGenerator's auto-generated hash suffix do your rollout triggering for you — because the ConfigMap name changes whenever content changes, any Deployment referencing it gets a new pod template hash and rolls automatically, no manual `kubectl rollout restart` needed.
