Kustomize: Change Image, Tag or Registry

Kustomize is a tool for customizing Kubernetes configurations.

Like for secrets, in Kustomize, there is a custom directive that allows to easily override names, tags and change registries (repositories) of container images (e.g. Docker images).

This short note shows how to change the image name, tag or registry using Kustomize.

Change Image, Tag or Registry using Kustomize

In nutshell, to change the image name, tag or registry you can declare a special images directive inside the kustomization.yaml:

images:
 - name: <imageName>
   newName: <newImageName>
   newTag: <newImageTag>

For example, let’s say your project has a file structure as follows:

~/myApp
├── pod.yaml
└── kustomization.yaml

The myapp-pod resource in the pod.yaml file declares a container that uses the image busybox with the tag 1.36.0:

# ~/myApp/pod.yaml
apiVersion: v1
kind: Pod
metadata:
  name: myapp-pod
spec:
  containers:
  - name: myapp-container
    image: busybox:1.36.0
    command: ['sh', '-c', 'echo The app is running! && sleep 3600']

The image busybox, as well as the tag 1.36.0 can be changed by updating the kustomization.yaml file, for example, as follows:

# ~/myApp/kustomization.yaml
resources:
- pod.yaml

images:
 - name: busybox
   newName: my-private.docker.registry/alpine
   newTag: 3.17.3

To verify that the image has been updated, run:

$ kubectl kustomize ~/myApp

In the example above, the busybox image has been replaced by the alpine image with the tag 3.17.3, hosted in a private Docker registry.

The same way you can change multiple images and tags in the kustomization.yaml, e.g.:

# ~/myApp/kustomization.yaml
resources:
- pod.yaml

images:
 - name: nginx
   newName: haproxy
   newTag: 2.8
 - name: redis
   newName: memcached
   newTag: 1.6.19