11.06 Common Transformers in Kustomize

Abstract

Common transformers in Kustomize apply the same change across multiple Kubernetes resources.

They help avoid manually editing every YAML file when you need shared labels, annotations, namespaces, or naming conventions.

Why Common Transformers?

In production, applications usually contain many Kubernetes resources:

Deployments
Services
ConfigMaps
Secrets
Ingress
ServiceAccounts
Jobs
StatefulSets

Manually adding the same label, namespace, annotation, prefix, or suffix to every file is repetitive and error-prone.

Warning

Do not manually update common metadata across many YAML files. It increases the chance of drift between environments.

Common Transformations

Transformer	Purpose
`commonLabels`	Adds labels to all managed resources
`namespace`	Adds a common namespace to all resources
`namePrefix`	Adds a prefix to all resource names
`nameSuffix`	Adds a suffix to all resource names
`commonAnnotations`	Adds annotations to all managed resources

Note

These transformations apply only to resources listed or imported by the current kustomization.yaml.

Base Example

Assume this service exists:

apiVersion: v1
kind: Service
metadata:
  name: api-service
spec:
  ports:
    - port: 80
      protocol: TCP
      targetPort: 3000
  selector:
    component: api
  type: LoadBalancer

Kustomize can transform this resource without editing the original YAML directly.

commonLabels Transformer

commonLabels adds labels to all resources managed by Kustomize.

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

resources:
  - db-service.yaml

commonLabels:
  org: KodeKloud

Rendered output:

apiVersion: v1
kind: Service
metadata:
  labels:
    org: KodeKloud
  name: api-service
spec:
  selector:
    component: api
    org: KodeKloud
  ports:
    - port: 80
      protocol: TCP
      targetPort: 3000
  type: LoadBalancer

Tip

Labels are useful for grouping, filtering, monitoring, billing, ownership, and automation.

Example commands:

kubectl get all -l org=KodeKloud
kubectl get pods --show-labels

Warning

Be careful when changing labels that are used by selectors. A wrong label change can break Service-to-Pod routing.

namespace Transformer

The namespace transformer places all resources into the same namespace.

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

resources:
  - db-service.yaml

namespace: lab

Rendered output:

apiVersion: v1
kind: Service
metadata:
  name: api-service
  namespace: lab
spec:
  ports:
    - port: 80
      protocol: TCP
      targetPort: 3000
  selector:
    component: api
  type: LoadBalancer

Success

Use namespaces to separate environments, teams, or applications.

Example:

kubectl apply -k k8s/
kubectl get svc -n lab

Warning

Kustomize does not automatically create the namespace unless you include a Namespace resource in resources.

Add it explicitly:

apiVersion: v1
kind: Namespace
metadata:
  name: lab

Then reference it:

resources:
  - namespace.yaml
  - db-service.yaml

namespace: lab

namePrefix and nameSuffix Transformers

Use namePrefix and nameSuffix to apply naming standards across resources.

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

resources:
  - db-service.yaml

namePrefix: KodeKloud-
nameSuffix: -dev

Original name:

metadata:
  name: api-service

Rendered name:

metadata:
  name: KodeKloud-api-service-dev

Example

This is useful when deploying the same base manifests into multiple environments.

Example:

dev-api-service
stg-api-service
prod-api-service

Warning

Avoid uppercase letters in real Kubernetes resource names.

Kubernetes DNS-compatible names should usually be lowercase. Prefer:

namePrefix: kodekloud-
nameSuffix: -dev

commonAnnotations Transformer

commonAnnotations adds metadata annotations to all resources.

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

resources:
  - db-service.yaml

commonAnnotations:
  branch: master

Rendered output:

apiVersion: v1
kind: Service
metadata:
  annotations:
    branch: master
  name: api-service
spec:
  ports:
    - port: 80
      protocol: TCP
      targetPort: 3000
  selector:
    component: api
  type: LoadBalancer

Note

Labels are usually for selection and grouping.

Annotations are usually for metadata, tooling, automation, build info, and controller-specific configuration.

Labels vs Annotations

Use Case	Prefer
Select pods	Labels
Filter resources	Labels
Team or app ownership	Labels
Git commit SHA	Annotations
Build metadata	Annotations
Tool-specific config	Annotations

Which one should I use?

Use labels when Kubernetes or users need to select/filter the object.

Use annotations when you only need to attach extra metadata.

Combined Example

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

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

namespace: lab

namePrefix: kodekloud-
nameSuffix: -dev

commonLabels:
  org: kodekloud
  environment: dev
  app.kubernetes.io/managed-by: kustomize

commonAnnotations:
  branch: master
  owner: platform-team

Build:

kustomize build k8s/

Apply:

kubectl apply -k k8s/

Environment Example

devstagingprod

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

resources:
  - ../../base

namespace: dev

nameSuffix: -dev

commonLabels:
  environment: dev

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

resources:
  - ../../base

namespace: staging

nameSuffix: -stg

commonLabels:
  environment: staging

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

resources:
  - ../../base

namespace: prod

nameSuffix: -prod

commonLabels:
  environment: prod

Tip

This keeps the base YAML reusable while each environment applies its own metadata and naming rules.

Production Best Practices

Recommended

Use lowercase names in namePrefix and nameSuffix
Use consistent labels across all workloads
Add ownership labels such as team, app, and environment
Use namespaces for environment or team isolation
Keep annotations for metadata, not selectors
Review generated YAML before applying to production

Useful validation command:

kustomize build overlays/prod/

Production apply:

kubectl diff -k overlays/prod/
kubectl apply -k overlays/prod/

Do's

Use commonLabels for app, team, environment, and ownership
Use namespace to keep resources isolated
Use namePrefix and nameSuffix for environment naming
Use commonAnnotations for metadata like branch, commit, or owner
Keep transformations in overlays when they differ by environment

Don'ts

Don't use uppercase resource names in production
Don't use annotations for pod/service selection
Don't change selector labels carelessly
Don't hardcode environment-specific names in base manifests
Don't apply production overlays without checking rendered output

Common Mistakes

Avoid these

Adding labels that accidentally change selectors
Setting namespace but forgetting to create the Namespace
Using different naming conventions across environments
Putting production-specific transformations in the base
Using annotations when labels are required for selectors

Troubleshooting

Issue	What to Check
Service cannot find Pods	Check selector labels after `commonLabels`
Resource created in wrong namespace	Check `namespace` in overlay
Namespace not found	Add a Namespace manifest
Resource name changed unexpectedly	Check `namePrefix` and `nameSuffix`
Annotation missing	Confirm the resource is included under `resources`

Commands:

kustomize build k8s/
kubectl apply -k k8s/
kubectl get all -n lab --show-labels
kubectl describe svc api-service -n lab
kubectl diff -k overlays/prod/

Bug

If a transformed resource does not look correct, run kustomize build first and inspect the final YAML before applying it.

Summary

Quote

Common transformers apply shared changes across many resources
commonLabels adds labels
namespace sets a namespace
namePrefix and nameSuffix rename resources
commonAnnotations adds metadata
In production, use these carefully because labels and names can affect selectors, routing, monitoring, and automation