11.07 Image Transformers in Kustomize

Abstract

The Image Transformer in Kustomize updates container images without editing the original Kubernetes manifest files.

It is commonly used to replace an image name, update an image tag, or change both image name and tag per environment.

Why Image Transformers?

In Kubernetes manifests, container images are usually defined inside Deployments, StatefulSets, DaemonSets, Jobs, or CronJobs.

Example:

containers:
  - name: web
    image: nginx

If you need to deploy a different image or tag for each environment, manually editing YAML files is not scalable.

Tip

Use Image Transformers when the same base manifest should run different image versions in dev, staging, and prod.

Key Point

Warning

The name field under images refers to the image name, not the container name.

In this Deployment:

containers:
  - name: web
    image: nginx

Container name = web
Image name = nginx

So this Kustomize transformer targets nginx, not web.

Base Deployment Example

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

This base manifest deploys an nginx container.

Replace Image Name

Use newName when you want to replace the image name.

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

resources:
  - web-depl.yaml

images:
  - name: nginx
    newName: haproxy

Rendered output:

containers:
  - name: web
    image: haproxy

Example

This replaces every container image named nginx with haproxy.

Replace Image Tag

Use newTag when you want to keep the image name but change the tag.

Warning

In Kustomize, newTag should be provided as a string. Do not leave numeric-looking tags unquoted.

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

resources:
  - web-depl.yaml

images:
  - name: nginx
    newTag: "2.4"

Rendered output:

containers:
  - name: web
    image: nginx:2.4

Note

newTag expects a string value. Always quote tags such as "2.4", "1.25.3", "2026-05-25", or "prod" to keep the value clearly treated as a string.

Replace Image Name and Tag

You can use both newName and newTag together. newTag should still be written as a quoted string.

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

resources:
  - web-depl.yaml

images:
  - name: nginx
    newName: haproxy
    newTag: "2.4"

Rendered output:

containers:
  - name: web
    image: haproxy:2.4

Success

This is useful when promoting an application from one image repository or runtime image to another.

Environment-Based Image Updates

A common production pattern is to keep a reusable base and override only the image tag in overlays.

k8s/
├── base/
│   ├── deployment.yaml
│   ├── service.yaml
│   └── kustomization.yaml
└── overlays/
    ├── dev/
    │   └── kustomization.yaml
    ├── staging/
    │   └── kustomization.yaml
    └── prod/
        └── kustomization.yaml

base/kustomization.yamloverlays/dev/kustomization.yamloverlays/staging/kustomization.yamloverlays/prod/kustomization.yaml

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

resources:
  - deployment.yaml
  - service.yaml

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

resources:
  - ../../base

images:
  - name: nginx
    newTag: "1.25-dev"

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

resources:
  - ../../base

images:
  - name: nginx
    newTag: "1.25-rc"

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

resources:
  - ../../base

images:
  - name: nginx
    newTag: "1.25.3"

Tip

Keep image changes in overlays, not in base, when different environments use different versions.

Using Private Registries

You can replace a public image with an internal registry image.

images:
  - name: nginx
    newName: registry.example.com/platform/nginx
    newTag: "1.25.3"

Rendered output:

image: registry.example.com/platform/nginx:1.25.3

Note

Make sure the namespace has the required imagePullSecrets if the registry is private.

Example:

spec:
  imagePullSecrets:
    - name: regcred

Commands

Build the final manifest:

kustomize build overlays/dev/

Apply directly with kubectl:

kubectl apply -k overlays/dev/

Preview production changes before applying:

kubectl diff -k overlays/prod/

Apply production overlay:

kubectl apply -k overlays/prod/

Check deployed image:

kubectl get deployment web-deployment -o=jsonpath='{.spec.template.spec.containers[*].image}'

Production Best Practices

Recommended

Pin image tags to exact versions in production
Prefer immutable tags or image digests for critical workloads
Keep base manifests generic and environment-specific image changes in overlays
Use kubectl diff -k before applying production changes
Store image updates in Git for traceability
Use CI/CD to update image tags automatically after successful builds

Image Tags vs Digests

Method	Example	Production Use
Floating tag	`nginx:latest`	Avoid
Version tag	`nginx:1.25.3`	Good
Build tag	`app:2026-05-25-1042`	Good
Digest	`nginx@sha256:...`	Best for immutability

Warning

Avoid latest in production. It can change unexpectedly and make rollbacks harder.

Do's

Use newTag as a quoted string to promote versions across environments
Use newName to switch registries or base images
Quote image tags in YAML
Validate rendered output using kustomize build
Use GitOps or CI/CD to manage image updates

Don'ts

Don't confuse container name with image name
Don't use latest for production workloads
Don't manually edit generated manifests
Don't update production image tags without review or rollback planning
Don't store registry credentials directly in manifests

Common Mistakes

Avoid these

Targeting the wrong image name in images
Forgetting to quote numeric tags like 2.4
Updating the base image when only one environment needs the change
Using mutable tags in production
Applying changes without checking the rendered manifest first

Troubleshooting

Issue	What to Check
Image did not change	Confirm `images.name` matches the original image exactly
Wrong image deployed	Run `kustomize build` and inspect final output
Pod stuck in `ImagePullBackOff`	Check image name, tag, registry access, and `imagePullSecrets`
Prod changed unexpectedly	Check overlay inheritance and Git history
Tag parsed incorrectly	Quote the tag value

Useful commands:

kustomize build overlays/prod/ | grep image:
kubectl describe pod <pod-name>
kubectl get events --sort-by=.lastTimestamp
kubectl get deployment web-deployment -o yaml

Bug

If a Pod fails with ImagePullBackOff, confirm the transformed image exists in the registry and the cluster has permission to pull it.

Quick Reference

images:
  - name: nginx
    newName: haproxy
    newTag: "2.4"

Result:

image: haproxy:2.4

Quote

Image Transformers let you reuse the same Kubernetes base manifests while safely changing container images per environment.