Transformers Demo

This lesson demonstrates common Kustomize transformers—commonLabels, namePrefix/nameSuffix, namespace, commonAnnotations—and the images transformer. The example repository layout has two component directories under a top-level k8s/ directory:

k8s/
- api/
  - api-depl.yaml
  - api-service.yaml
  - kustomization.yaml
- db/
  - db-depl.yaml
  - db-service.yaml
  - db-config.yaml
  - kustomization.yaml
- kustomization.yaml (root)

Below are the important kustomization.yaml files and a step-by-step walkthrough showing how each transformer is applied and what resources it affects.

This guide focuses on transformer scope: where you place a transformer (root vs. subdirectory) determines which resources get modified. Use kustomize build <dir> to inspect the composed manifests after each change.

Subdirectory kustomization files

Each component folder lists its own resources in a kustomization.yaml. Example: api/kustomization.yaml

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

resources:
  - api-depl.yaml
  - api-service.yaml

Example: db/kustomization.yaml

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

resources:
  - db-config.yaml
  - db-depl.yaml
  - db-service.yaml

The root kustomization.yaml composes the API and DB overlays:

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

resources:
  - api/
  - db/

Run a build to view the combined manifests:

$ kustomize build k8s

1) Apply a global common label

To add the same label to every resource produced by the root composition, set commonLabels in the root kustomization.yaml:

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

resources:
  - api/
  - db/

commonLabels:
  department: engineering

Build and inspect the YAML—you’ll see the label applied across resources:

apiVersion: v1
kind: ConfigMap
metadata:
  name: db-credentials
  labels:
    department: engineering
data:
  username: root
  password: example
---
apiVersion: v1
kind: Service
metadata:
  name: api-service
  labels:
    department: engineering
spec:
  ports:
    - port: 80
      protocol: TCP
      targetPort: 3000
  selector:
    component: api
    department: engineering
  type: LoadBalancer

All resources produced by the root composition (both api/ and db/) include the department: engineering label.

2) Apply labels scoped to a subdirectory

If you set commonLabels in a subdirectory kustomization.yaml, the label only applies to the resources listed by that kustomization. Example: add a label in api/kustomization.yaml:

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

resources:
  - api-depl.yaml
  - api-service.yaml

commonLabels:
  feature: api

After building:

Resources under api/ include feature: api.
Resources under db/ do NOT include feature: api (they still only have any root-level labels, e.g. department: engineering if configured).

To give the DB overlay its own label, add in db/kustomization.yaml:

commonLabels:
  feature: db

Now DB resources receive feature: db. This demonstrates that transformers declared in a kustomization only affect resources declared by that kustomization (and any children it references).

3) Set a namespace globally

To assign all generated resources to a specific namespace from the root, add namespace:

resources:
  - api/
  - db/

commonLabels:
  department: engineering

namespace: debugging

After kustomize build k8s, resources that support namespaces will include:

metadata:
  namespace: debugging

4) Name prefix and name suffix

Use namePrefix at the root for a global prefix:

namePrefix: KodeKloud-

Include the trailing dash to avoid concatenated names. Use nameSuffix in subdirectory kustomizations to append a suffix only to that overlay’s resources. Example: api/kustomization.yaml

nameSuffix: -web

Example: db/kustomization.yaml

nameSuffix: -storage

Resulting name transformations:

API deployment original api-deployment -> KodeKloud-api-deployment-web
DB deployment original db-deployment -> KodeKloud-db-deployment-storage

Note: prefix is applied globally at root; suffixes are applied per subdirectory.

5) Add common annotations

To add the same annotation to every generated resource, use commonAnnotations at the root:

commonAnnotations:
  logging: verbose

Rebuild to see logging: verbose appear under metadata.annotations for each resource.

6) Image transformer (rewrite container images)

The images transformer rewrites image names and tags. Placement controls scope:

images: in the root kustomization affects any resource in the composition that references the image.
images: in a subdirectory affects only resources listed by that subdirectory.

Example: rewrite mongo to Postgres only in the DB overlay by adding to db/kustomization.yaml:

images:
  - name: mongo
    newName: postgres
    newTag: "4.2"

Always quote newTag (e.g. "4.2") so Kustomize parses it as a string. Unquoted numeric tags can cause an error like: “cannot unmarshal number into Go struct field image of type string”.

After building, the DB Deployment’s container spec will show the image rewritten:

spec:
  containers:
    - name: mongo
      image: postgres:4.2
      env:
        - name: MONGO_INITDB_ROOT_USERNAME
          valueFrom:
            configMapKeyRef:
              name: KodeKloud-db-credentials-storage
              key: username
        - name: MONGO_INITDB_ROOT_PASSWORD
          valueFrom:
            configMapKeyRef:
              name: KodeKloud-db-credentials-storage
              key: password

Note: the container name: mongo remains unchanged; only the image field is rewritten. If you move the same images block to the root kustomization.yaml, every resource referencing mongo anywhere in the composed output would be rewritten to postgres:4.2.

Quick reference: transformer scope

Transformer	Typical use	Placement determines scope
`commonLabels`	Add labels to many resources	Root = global; Subdir = scoped to that overlay
`commonAnnotations`	Add annotations globally	Root = global
`namespace`	Set target namespace	Root = global
`namePrefix`	Apply consistent global prefix	Root (recommended)
`nameSuffix`	Distinguish overlay resources	Subdir (applies only to that overlay)
`images`	Rewrite image name and/or tag	Root = everywhere; Subdir = overlay-only

Summary

Place commonLabels, commonAnnotations, namespace, and namePrefix in the root kustomization.yaml to affect the entire composition.
Place commonLabels, nameSuffix, images, or other overlay-specific transformers in a subdirectory kustomization.yaml to limit their effect to that overlay’s resources.
The images transformer matches existing image names and rewrites newName and newTag (use quotes for newTag).
Use namePrefix at root for a consistent global prefix and nameSuffix in components to distinguish resources by component.

This completes the lesson. A hands-on lab is available to practice these transformers.

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

Subdirectory kustomization files

1) Apply a global common label

2) Apply labels scoped to a subdirectory

3) Set a namespace globally

4) Name prefix and name suffix

5) Add common annotations

6) Image transformer (rewrite container images)

Quick reference: transformer scope

Summary

Links and References

Watch Video

Practice Lab

​Subdirectory kustomization files

​1) Apply a global common label

​2) Apply labels scoped to a subdirectory

​3) Set a namespace globally

​4) Name prefix and name suffix

​5) Add common annotations

​6) Image transformer (rewrite container images)

​Quick reference: transformer scope

​Summary

​Links and References

Watch Video

Practice Lab

Subdirectory kustomization files

1) Apply a global common label

2) Apply labels scoped to a subdirectory

3) Set a namespace globally

4) Name prefix and name suffix

5) Add common annotations

6) Image transformer (rewrite container images)

Quick reference: transformer scope

Summary

Links and References