Kustomize’s dry run feature is your safety net, letting you preview exactly what Kubernetes manifests will be generated without actually creating or modifying any resources.
Let’s see it in action. Imagine you have a kustomization.yaml file like this:
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- base/
images:
- name: my-app
newName: my-app-staging
newTag: v1.2.3
patchesStrategicMerge:
- patch.yaml
And a patch.yaml:
apiVersion: apps/v1
kind: Deployment
metadata:
name: my-app
spec:
template:
spec:
containers:
- name: my-app
image: my-app:latest # This will be replaced by the image tag
To see what Kustomize will output before applying it to your cluster, you use the kustomize build command, which is effectively a dry run.
kustomize build .
This command will process your kustomization.yaml and all associated files (like those in base/ and patch.yaml) and print the resulting Kubernetes YAML manifests to standard output. You can then pipe this output to kubectl diff or kubectl apply --dry-run=client for even more detailed validation.
kustomize build . | kubectl diff -f -
This combination shows you the difference between your current cluster state and what Kustomize would apply, highlighting any unexpected changes.
The Mental Model: Kustomize as a Manifest Generator
Think of Kustomize not as a deployment tool itself, but as a powerful manifest generator. It takes a base set of Kubernetes YAML files and applies declarative customizations to them. These customizations can include:
- Resource Inclusion: Specifying which base YAML files or directories to start with.
- Image Tagging: Globally replacing image names and tags across all resources, crucial for managing different environments (dev, staging, prod).
- Strategic Merge Patches: Applying targeted modifications to existing resources based on their
apiVersion,kind,name, andnamespace. This is how you’d change replicas, update container images, or add annotations without rewriting the entire base manifest. - JSON Patches: More granular, path-based modifications.
- ConfigMap/Secret Generation: Automatically creating or transforming ConfigMaps and Secrets from literal values, files, or directories.
- Name Prefix/Suffix: Adding common prefixes or suffixes to resource names for better organization.
The kustomization.yaml file is the central orchestrator. It declares the "build process" – what to start with, what to patch, and what to generate. When you run kustomize build, Kustomize executes these instructions sequentially. It fetches resources, applies image overrides, merges patches, and generates new resources. The output is a single, consolidated stream of Kubernetes YAML ready to be applied.
The Core Problem Kustomize Solves: Managing Configuration Drift
Without Kustomize, managing multiple environments (dev, staging, prod) often leads to copy-pasted YAML files with minor, hard-to-track differences. Updating a Deployment in one environment might be missed in another, leading to configuration drift. Kustomize addresses this by defining a single "base" configuration and then layering environment-specific differences (overlays). This ensures consistency and reduces errors.
The Levers You Control:
resources: The starting point. Can be a list of files or directories containing base YAML.bases: Similar toresources, but specifically for referencing other Kustomize directories.patchesStrategicMerge: The most common way to modify existing resources. You provide partial YAML, and Kustomize merges it based on resource identity.patchesJson6902: For more precise, path-based modifications using JSON Patch syntax.images: Essential for CI/CD. Definename,newName, andnewTagto systematically update container images.commonLabels/commonAnnotations: Apply labels or annotations to all resources in the kustomization.namePrefix/nameSuffix: Useful for isolating resources within a single cluster, e.g.,staging-my-app.configMapGenerator/secretGenerator: Powerful for managing configuration data directly within Kustomize.
The Counterintuitive Detail: Patches Don’t Replace, They Merge
When you use patchesStrategicMerge, Kustomize doesn’t just slap your patch YAML on top of the base. It performs a strategic merge. This means if your base Deployment has multiple containers and your patch only specifies one, Kustomize will keep the other containers from the base. It intelligently merges lists and maps. For example, if your base spec.template.spec.containers has container-a and container-b, and your patch targets container-a to change its image, Kustomize will produce a manifest with both container-a (with the updated image) and container-b. This is different from a simple overwrite and is key to managing complex resources without full replication.
The next step after validating with dry run is often integrating Kustomize into your CI/CD pipeline to automate deployments.