Kustomize’s built-in transformers are surprisingly malleable, allowing you to modify their behavior without writing entirely new plugins.
Let’s see how we can tweak the commonLabels transformer to apply labels only to specific resources.
# kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- deployment.yaml
- service.yaml
transformers:
- commonLabelsTransformer.yaml
# commonLabelsTransformer.yaml
apiVersion: builtin.kustomize.io/v1alpha1
kind: CommonLabelsTransformer
metadata:
name: transformer
labels:
app.kubernetes.io/managed-by: kustomize
environment: production
# This is where the magic happens: filtering
fieldRef:
- kind: Deployment
- kind: Service
# deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: my-app
spec:
replicas: 3
selector:
matchLabels:
app: my-app
template:
metadata:
labels:
app: my-app
spec:
containers:
- name: nginx
image: nginx:latest
# service.yaml
apiVersion: v1
kind: Service
metadata:
name: my-app-service
spec:
selector:
app: my-app
ports:
- protocol: TCP
port: 80
targetPort: 80
Running kustomize build . with these files will produce:
apiVersion: apps/v1
kind: Deployment
metadata:
labels:
app.kubernetes.io/managed-by: kustomize
environment: production
name: my-app
spec:
replicas: 3
selector:
matchLabels:
app: my-app
template:
metadata:
labels:
app: my-app
spec:
containers:
- image: nginx:latest
name: nginx
---
apiVersion: v1
kind: Service
metadata:
labels:
app.kubernetes.io/managed-by: kustomize
environment: production
name: my-app-service
spec:
ports:
- port: 80
protocol: TCP
targetPort: 80
selector:
app: my-app
Notice how app.kubernetes.io/managed-by: kustomize and environment: production are applied to both the Deployment and Service resources. This is because we explicitly listed kind: Deployment and kind: Service under the fieldRef in our transformer configuration.
The core problem Kustomize solves is managing complex Kubernetes configurations across different environments and stages of a deployment lifecycle. Instead of manually editing YAML files for each change (e.g., adding labels for production, changing replica counts for staging), Kustomize allows you to define a base configuration and then apply layered customizations. Built-in transformers are the workhorses of this system, performing common operations like adding labels, patching existing resources, or generating secrets.
The CommonLabelsTransformer is designed to add a consistent set of labels to all resources defined in your kustomization.yaml. However, by leveraging the fieldRef field within the transformer’s configuration, you gain fine-grained control. fieldRef accepts a list of map entries, where each entry specifies a kind of Kubernetes resource. When fieldRef is present, the transformer only applies its changes to resources matching those kinds. If fieldRef is omitted, the transformer would apply to all resources in the kustomization. If you wanted to be even more specific, you could use name or group within fieldRef to target resources by their name or API group.
This fieldRef mechanism isn’t unique to CommonLabelsTransformer; many other built-in transformers support similar filtering capabilities. For instance, the CommonAnnotationsTransformer works identically, and the PatchTransformer can also be scoped using fieldRef. This provides a powerful declarative way to dictate where modifications should and should not occur within your Kubernetes manifests, making your Kustomize configurations more precise and less prone to unintended side effects.
What most people miss is that you can define multiple fieldRef entries to target a diverse set of resources. For example, to apply labels only to Deployments and StatefulSets, you would simply add another entry to the fieldRef list:
fieldRef:
- kind: Deployment
- kind: StatefulSet
This allows for highly granular application of common metadata or patches across different resource types within a single transformer configuration, reducing the need for multiple, near-identical transformer definitions.
The next step in mastering Kustomize is exploring how to combine multiple transformers and manage their execution order.