Image Transformers

In this lesson you’ll learn how to use Kustomize’s image transformer to update container images (name and/or tag) in Kubernetes manifests without editing the original resource files. This is especially useful for environment-specific overrides, CI/CD pipelines, or replacing images across many manifests in a single place. Below are concise, practical examples that show:

a Deployment manifest (original),
Kustomize images: transformations (in kustomization.yaml),
the resulting rendered manifests after running kustomize build or kubectl kustomize.

Initial Deployment (deployment.yaml)

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web-deployment
spec:
  replicas: 1
  selector:
    matchLabels:
      component: web
  template:
    metadata:
      labels:
        component: web
    spec:
      containers:
        - name: web
          image: nginx

Example 1 — Replace the image name (newName)

kustomization snippet that replaces the base image name nginx with haproxy:

# kustomization.yaml
images:
- name: nginx
  newName: haproxy

How to preview or apply the transformation:

kustomize build .
# or with kubectl:
kubectl kustomize .  # prints the transformed YAML
# to apply:
kubectl apply -k .

Rendered Deployment after applying the newName transform:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web-deployment
spec:
  replicas: 1
  selector:
    matchLabels:
      component: web
  template:
    metadata:
      labels:
        component: web
    spec:
      containers:
        - name: web
          image: haproxy

Note: The name field under images: in kustomization.yaml matches the image reference (for example nginx), not the container name in the Pod/Deployment spec. The container’s name: web is independent and does not affect Kustomize image matching.

Example 2 — Change only the tag (newTag)

If you want to keep the same image name but change the tag:

# kustomization.yaml
images:
- name: nginx
  newTag: "2.4"

Rendered Deployment after applying the newTag transform:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web-deployment
spec:
  replicas: 1
  selector:
    matchLabels:
      component: web
  template:
    metadata:
      labels:
        component: web
    spec:
      containers:
        - name: web
          image: nginx:2.4

Example 3 — Change both name and tag (newName + newTag)

To replace both the image name and the tag in one transform:

# kustomization.yaml
images:
- name: nginx
  newName: haproxy
  newTag: "2.4"

Rendered Deployment after applying both newName and newTag:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web-deployment
spec:
  replicas: 1
  selector:
    matchLabels:
      component: web
  template:
    metadata:
      labels:
        component: web
    spec:
      containers:
        - name: web
          image: haproxy:2.4

Quick reference table

Transformation	kustomization `images:` entry	Resulting image
Replace name only	`name: nginx` / `newName: haproxy`	`haproxy`
Replace tag only	`name: nginx` / `newTag: "2.4"`	`nginx:2.4`
Replace name + tag	`name: nginx` / `newName: haproxy` / `newTag: "2.4"`	`haproxy:2.4`

Additional notes and best practices

You can include multiple entries in the images: list to transform several different base images in one kustomization.yaml.
Matching is strict: use the same base reference as in your manifests (for example nginx, nginx:1.21, or a full registry path like gcr.io/myproj/nginx) to ensure replacements occur as expected.
Always preview transformations with kustomize build or kubectl kustomize before applying them with kubectl apply -k ..
Use Kustomize overlays (separate kustomization directories) for environment-specific image overrides (dev, staging, prod) to keep base manifests immutable.

Links and references

Kustomize documentation: https://kubectl.docs.kubernetes.io/guides/introduction/kustomize/
kubectl kustomize: https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands#kustomize
Kustomize images transformer reference: https://kubectl.docs.kubernetes.io/references/kustomize/kustomization/imageTransformers/

Introduction

Core Concepts

Scheduling

Logging & Monitoring

Application Lifecycle Management

Cluster Maintenance

Security

Storage

Networking

Design and Install a Kubernetes Cluster

Install "Kubernetes the kubeadm way"

Troubleshooting

Helm Basics (2025 Updates)

Kustomize Basics (2025 Updates)

Other Topics

Mock Exams

Image Transformers

Initial Deployment (deployment.yaml)

Example 1 — Replace the image name (newName)

Example 2 — Change only the tag (newTag)

Example 3 — Change both name and tag (newName + newTag)

Quick reference table

Additional notes and best practices

Links and references

Watch Video

​Initial Deployment (deployment.yaml)

​Example 1 — Replace the image name (newName)

​Example 2 — Change only the tag (newTag)

​Example 3 — Change both name and tag (newName + newTag)

​Quick reference table

​Additional notes and best practices

​Links and references

Watch Video

Initial Deployment (deployment.yaml)

Example 1 — Replace the image name (newName)

Example 2 — Change only the tag (newTag)

Example 3 — Change both name and tag (newName + newTag)

Quick reference table

Additional notes and best practices

Links and references