Kustomize

Kustomize cheatsheet — build, preview, and apply Kubernetes configs with overlays. kubectl kustomize, kustomize build ./overlays/prod. Template-free K8s customization.

5 min read

What it is

A tool for customizing Kubernetes configurations without templating, allowing you to overlay patches and additions onto base YAML definitions.

Installation

Linux

curl -s "https://raw.githubusercontent.com/kubernetes-sigs/kustomize/master/hack/install_kustomize.sh"  | bash
# This will download the latest kustomize binary to your current directory.
# To install it system-wide (e.g., for all users):
sudo mv kustomize /usr/local/bin/

macOS

brew install kustomize

Windows

Download the appropriate binary from the Kustomize releases page on GitHub and add it to your system’s PATH.

Core Concepts

Base: The original, unpatched Kubernetes manifests (YAML files).
Overlay: A directory containing customizations applied to a base.
kustomization.yaml: The central configuration file within an overlay directory that defines the base and the patches/modifications.
Patches: Modifications applied to existing resources. These can be strategic merges (adding/modifying fields) or JSON patches (more granular changes).
Generators: Resources created from scratch or from external data (like ConfigMaps from files).

Commands / Usage

Building and Applying Configurations

kustomize build <overlay-dir> Builds the Kubernetes manifests for the specified overlay directory and prints them to standard output.
```
kustomize build overlays/production
```
kustomize build <overlay-dir> > output.yaml Saves the built manifests to a file.
```
kustomize build overlays/staging > staging-manifests.yaml
```
kubectl apply -k <overlay-dir> Applies the Kustomize configuration directly to your Kubernetes cluster. This is the most common way to deploy Kustomize-managed applications.
```
kubectl apply -k overlays/development
```

Managing kustomization.yaml

kustomize create <dir> Initializes a kustomization.yaml file in the specified directory.

kustomize create --resources base/deployment --resources base/service my-app/overlays/dev

Viewing Differences

kustomize diff <overlay-dir> Shows the differences between the current state in the cluster and the Kustomize configuration.
```
kustomize diff overlays/production
```

Common Patterns

Overriding Image Tags

If your base has a deployment with image: nginx:latest, you can override the tag in an overlay.

base/deployment.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  template:
    spec:
      containers:
      - name: main
        image: nginx:latest

overlays/production/kustomization.yaml:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - ../../base

images:
- name: nginx
  newName: nginx
  newTag: 1.21.0

Command:

kustomize build overlays/production

This will output a deployment with image: nginx:1.21.0.

Adding Labels to All Resources

Apply a common label to all resources defined in the base.

overlays/staging/kustomization.yaml:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - ../../base

commonLabels:
  env: staging

Command:

kustomize build overlays/staging

This will add env: staging to the metadata.labels of all resources.

Patching Specific Fields

Modify a specific field in an existing resource.

base/deployment.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  replicas: 1

overlays/production/deployment-patch.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  replicas: 3

overlays/production/kustomization.yaml:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - ../../base

patchesStrategicMerge:
  - deployment-patch.yaml

Command:

kustomize build overlays/production

This will output a deployment with replicas: 3.

Patching with JSON Patches

For more granular control, use JSON patches.

base/deployment.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  template:
    spec:
      containers:
      - name: main
        resources:
          requests:
            cpu: "100m"

overlays/dev/container-patch.json:

[
  {
    "op": "replace",
    "path": "/spec/template/spec/containers/0/resources/requests/cpu",
    "value": "200m"
  }
]

overlays/dev/kustomization.yaml:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - ../../base

patchesJson6902:
  - target:
      kind: Deployment
      name: my-app
    path: container-patch.json

Command:

kustomize build overlays/dev

This will output a deployment with cpu: "200m" in the requests.

Creating ConfigMaps from Files

Generate a ConfigMap from one or more files.

base/config/app-config.properties:

FEATURE_FLAG_X=true

overlays/production/kustomization.yaml:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - ../../base

configMapGenerator:
- name: app-config
  files:
  - app-config.properties

Command:

kustomize build overlays/production

This will output a ConfigMap named app-config with the data from app-config.properties.

Creating Secrets from Files

Similar to ConfigMaps, but for sensitive data.

base/secrets/api-key.txt:

my-super-secret-key-12345

overlays/production/kustomization.yaml:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - ../../base

secretGenerator:
- name: api-credentials
  files:
  - api-key.txt

Command:

kustomize build overlays/production

This will output a Secret named api-credentials with the data from api-key.txt encoded in base64.

Adding New Resources

Include additional Kubernetes manifests not present in the base.

overlays/dev/custom-resource.yaml:

apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: my-app-monitor
spec:
  selector:
    matchLabels:
      app: my-app

overlays/dev/kustomization.yaml:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - ../../base
  - custom-resource.yaml

Command:

kustomize build overlays/dev

This will output the base resources plus the ServiceMonitor.

Building Multiple Overlays Sequentially

Combine configurations from different overlays.

overlays/base/kustomization.yaml:

resources:
  - deployment.yaml
  - service.yaml

overlays/frontend/kustomization.yaml:

resources:
  - ../base
  - frontend-ingress.yaml
commonLabels:
  app: frontend

overlays/backend/kustomization.yaml:

resources:
  - ../base
  - backend-hpa.yaml
commonLabels:
  app: backend

Command:

kustomize build overlays/frontend > frontend.yaml
kustomize build overlays/backend > backend.yaml

This builds separate configurations for frontend and backend deployments.

Gotchas

kustomize build vs. kubectl apply -k: kustomize build only outputs YAML. kubectl apply -k actually applies the configuration to the cluster.
Name Collisions: If multiple resources in different bases or generated resources have the same name and namespace, Kustomize will error.
Patching Non-Existent Resources: Patches will fail if the target resource defined in the patch does not exist in the base or other included resources.
Order of Operations: Kustomize applies resources, generators, and patches in a specific order. Be mindful of this when dependencies exist.
newName vs. newTag: newName changes the image repository, while newTag changes only the tag. Use newName if you are also changing the repository.
patchesStrategicMerge vs. patchesJson6902: patchesStrategicMerge is simpler for most common modifications. patchesJson6902 offers more fine-grained control for complex changes or when patchesStrategicMerge doesn’t behave as expected.
kustomization.yaml Location: Kustomize commands must be run from a directory that contains or can access the kustomization.yaml file.
Namespaces: If a kustomization.yaml specifies a namespace, it applies to all resources unless overridden individually. If no namespace is specified, it uses the namespace from the base or the default namespace of the Kubernetes context.