Kustomize Cheatsheet

Template-free Kubernetes configuration management with bases, overlays, generators, and patches.

Install and Verify
Core Commands
Minimal kustomization.yaml
Bases and Overlays
Patching Resources
Generators
Cross-Cutting Settings
Images and Replicas
Debug and Diff Workflow
Practical Patterns

Install and Verify

Use either the standalone kustomize binary or the kubectl integration.


# macOS
brew install kustomize
 
# Verify standalone binary
kustomize version
 
# Verify kubectl integration
kubectl kustomize --help

Core Commands

Render manifests locally, then apply or diff them through kubectl.


# Render manifests from a directory
kustomize build ./
kubectl kustomize ./
 
# Apply an overlay directly
kubectl apply -k overlays/dev
kubectl apply -k overlays/prod
 
# Preview changes before apply
kubectl diff -k overlays/prod
 
# Delete everything defined by a kustomization
kubectl delete -k overlays/dev

Minimal kustomization.yaml

A kustomization lists resources and the transformations to apply without editing the original YAML files.


# kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - deployment.yaml
  - service.yaml
commonLabels:
  app.kubernetes.io/name: store-api
  app.kubernetes.io/part-of: zero-to-ai
namespace: demo


kustomize build .

Bases and Overlays

Keep reusable defaults in a base and environment-specific changes in overlays.


app/
  base/
    deployment.yaml
    service.yaml
    kustomization.yaml
  overlays/
    dev/
      kustomization.yaml
      patch-replicas.yaml
    prod/
      kustomization.yaml
      patch-resources.yaml


# overlays/dev/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - ../../base
nameSuffix: -dev
patches:
  - path: patch-replicas.yaml


# overlays/prod/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - ../../base
nameSuffix: -prod
patches:
  - path: patch-resources.yaml

Patching Resources

Use patches to adjust existing resources for an environment without copying the full manifest.


# overlays/dev/patch-replicas.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: store-api
spec:
  replicas: 2


# overlays/prod/kustomization.yaml with target selector
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - ../../base
patches:
  - path: patch-resources.yaml
    target:
      kind: Deployment
      name: store-api


# overlays/prod/patch-resources.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: store-api
spec:
  template:
    spec:
      containers:
        - name: api
          resources:
            requests:
              cpu: 250m
              memory: 256Mi
            limits:
              cpu: 500m
              memory: 512Mi

Generators

Let Kustomize generate ConfigMaps and Secrets from literals or files. Do not commit real secrets in plaintext.


# kustomization.yaml
configMapGenerator:
  - name: app-config
    literals:
      - LOG_LEVEL=debug
      - FEATURE_FLAG=true
    files:
      - application.properties
 
secretGenerator:
  - name: api-secrets
    literals:
      - DB_PASSWORD=replace-me
      - API_KEY=replace-me
 
generatorOptions:
  disableNameSuffixHash: false
  labels:
    managed-by: kustomize

Cross-Cutting Settings

Apply the same namespace, labels, annotations, or naming strategy to every resource in the set.


# kustomization.yaml
namespace: payments
namePrefix: team1-
nameSuffix: -v2
commonLabels:
  tier: backend
  owner: platform
commonAnnotations:
  repo: github.com/example/store-api


kustomize build overlays/dev

Images and Replicas

Update images or replica counts without touching the base manifest directly.


# kustomization.yaml
images:
  - name: nginx
    newName: ghcr.io/acme/nginx
    newTag: 1.27.0
 
replicas:
  - name: store-api
    count: 4


kustomize edit set image nginx=ghcr.io/acme/nginx:1.27.0
kustomize edit set namespace payments

Debug and Diff Workflow

Render first, inspect the YAML, then diff and apply.


# Render to stdout
kubectl kustomize overlays/dev
 
# Save rendered manifests for review
kustomize build overlays/prod > rendered-prod.yaml
 
# Validate output shape before apply
kubectl diff -k overlays/prod
kubectl apply -k overlays/prod
kubectl get all -n payments

Practical Patterns

Pattern 1: Keep vendor manifests untouched

Store upstream YAML in base/ and put your organization-specific labels, namespaces, and image changes in overlays.

Pattern 2: One overlay per environment

Use overlays/dev, overlays/staging, and overlays/prod for clean promotion paths.

Pattern 3: Generate config, patch workloads

Use configMapGenerator and secretGenerator for inputs, then patch Deployments to consume them.

Pattern 4: Prefer diff before apply

kubectl diff -k is the cheapest way to catch namespace, image, or naming mistakes before rollout.

Source alignment: Based on the Kubernetes Kustomize introduction and adapted into a quick-reference workflow.