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

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

Links and References

• Kustomize Image Transformer
• Kubernetes Basics
• kubectl Customization