Kustomize can manage configuration drift across many resources in a single operation.
Let’s say you have a Deployment and a Service for your application, and you want to update the image tag for both simultaneously.
Here’s a typical Kustomize setup in a kustomization.yaml file:
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- deployment.yaml
- service.yaml
images:
- name: my-app
newTag: v1.2.3
When you run kustomize build ., it will process deployment.yaml and service.yaml. If both of these files reference an image named my-app, Kustomize will find and update it to v1.2.3 in both.
This is powerful because it allows you to define a single source of truth for common configurations like image tags, environment variables, or resource limits, and apply them consistently across a multitude of Kubernetes objects.
Consider a more complex scenario where you have multiple deployments and stateful sets that all need to use the same configuration for a particular feature flag. Instead of patching each resource individually, you can leverage Kustomize’s patchesJson6902 or patchesStrategicMerge to apply a common change.
Let’s imagine you want to add an app.kubernetes.io/version label to all your deployments.
Your deployment.yaml might look like this:
apiVersion: apps/v1
kind: Deployment
metadata:
name: frontend
labels:
app: frontend
spec:
selector:
matchLabels:
app: frontend
template:
metadata:
labels:
app: frontend
spec:
containers:
- name: app
image: my-frontend:latest
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: backend
labels:
app: backend
spec:
selector:
matchLabels:
app: backend
template:
metadata:
labels:
app: backend
spec:
containers:
- name: app
image: my-backend:latest
And your kustomization.yaml could include a patch:
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- deployments.yaml
patchesStrategicMerge:
- patch-labels.yaml
The patch-labels.yaml would be:
apiVersion: apps/v1
kind: Deployment
metadata:
name: frontend # Kustomize matches by API version, kind, and name
spec:
template:
metadata:
labels:
app.kubernetes.io/version: "v1.5.0"
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: backend
spec:
template:
metadata:
labels:
app.kubernetes.io/version: "v1.5.0"
When kustomize build . is run, the patch-labels.yaml will be merged with each Deployment resource that matches the apiVersion, kind, and metadata.name. The result is that both frontend and backend deployments will have the app.kubernetes.io/version: "v1.5.0" label added to their spec.template.metadata.labels.
This declarative approach ensures that your cluster’s state always reflects your intended configuration, even as you manage numerous applications and their respective resources. The images field is particularly useful for managing image tags across a fleet of deployments, ensuring all your services are running the same version of your software.
The core mechanism behind this cross-cutting application of changes is Kustomize’s ability to perform declarative merges. When you specify an image under the images field, Kustomize iterates through all the resources it’s processing and looks for container definitions. If it finds a container whose image matches the name you’ve specified (e.g., my-app), it replaces the image field of that container with the newTag or newImage you’ve provided. Similarly, strategic merges and JSON patches are applied based on matching Kubernetes object identifiers.
A common misunderstanding is that Kustomize only modifies the spec.template.spec.containers[*].image field. However, Kustomize’s images directive can also modify spec.initContainers[*].image and even spec.containers[*].image directly within the pod template. This means if you have init containers in your deployments, their images can be updated simultaneously with your main application containers using the same images field in kustomization.yaml.
The next logical step is to explore how to manage secrets and configmaps that need to be injected into multiple resources consistently.