Image Transformers

Leverage Kustomize’s image transformer to override container images in your Kubernetes manifests without touching the original YAML files. This approach keeps your base configurations DRY and promotes reusability across environments.

Prerequisites

Kubernetes cluster or local setup (e.g., Docker Desktop, Minikube)
kubectl v1.18+
Kustomize v3.2+ (bundled with kubectl since v1.14)

For more details, see Kubernetes Documentation and Kustomize Official Guide.

1. Replace the Image Name

Suppose you have a Deployment manifest (deployment.yaml) deploying an NGINX container:

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

To swap nginx for haproxy, create a kustomization.yaml in the same directory:

images:
  - name: nginx
    newName: haproxy

Run the build command:

kustomize build .

Kustomize will find every nginx image reference and replace it with haproxy. The rendered Deployment becomes:

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

The name field under images matches the image name from your resources, not the container name in the Pod spec.

2. Change Only the Image Tag

If you want to keep nginx but bump its version tag to 2.4, specify newTag instead:

images:
  - name: nginx
    newTag: 2.4

After kustomize build ., the Deployment’s container image updates to:

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

3. Combine Image Name and Tag Changes

You can simultaneously override both the repository and the tag:

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

The resulting manifest will then reference haproxy:2.4:

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

Image Transformer Fields

Field	Description	Example
name	Original image name in your resources	`nginx`
newName	Replacement image repository or name	`haproxy`
newTag	New version tag for the image	`2.4`

Omitting both newName and newTag in an images entry has no effect. Ensure at least one property is set.

Introduction

Kustomize Basics

Secret/Config Generator

Other Commands

Kustomize Overview

Capstone Project

Image Transformers

Prerequisites

1. Replace the Image Name

2. Change Only the Image Tag

3. Combine Image Name and Tag Changes

Image Transformer Fields

Links and References

Watch Video

​Prerequisites

​1. Replace the Image Name

​2. Change Only the Image Tag

​3. Combine Image Name and Tag Changes

​Image Transformer Fields

​Links and References

Watch Video

Prerequisites

1. Replace the Image Name

2. Change Only the Image Tag

3. Combine Image Name and Tag Changes

Image Transformer Fields

Links and References