kustomization.yaml in depth — fields, transformers, and generators

The kustomization.yaml is the heart of Kustomize. This lesson walks the fields, the transformers, the generators, and the operational discipline.

The kustomization.yaml fields

flowchart LR
    A[kustomization.yaml fields] --> B[resources]
    A --> C[patches]
    A --> D[commonLabels]
    A --> E[namespace]
    A --> F[namePrefix]
    A --> G[transformers]
    A --> H[generators]
    A --> I[components]

The fields:

• resources — the input manifests.
• patches — modifications to specific resources.
• commonLabels — labels added to all resources.
• namespace — namespace for all resources.
• namePrefix — prefix for all resource names.
• transformers — automatic transformations (images, replicas, annotations).
• generators — automatic generation of ConfigMaps, Secrets.
• components — reusable kustomizations.

Resources and patches

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

resources:
  - deployment.yaml
  - service.yaml
  - https://example.com/manifests/job.yaml  # remote resource

patches:
  - path: patch-deployment.yaml  # strategic merge
    target:
      kind: Deployment
      name: myapp
  - patch: |-
      - op: replace
        path: /spec/replicas
        value: 5
    target:
      kind: Deployment
      name: myapp

resources lists the input files; patches apply modifications to specific resources (by kind and name). Patches can be inline (JSON 6902) or in separate files (strategic merge).

Transformers

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

resources:
  - deployment.yaml

# Image transformer: rewrite image references
images:
  - name: myapp
    newName: myapp
    newTag: "2.0.0"
  - name: postgres
    newName: registry.example.com/postgres
    newTag: "16"

# Replica transformer: set replica counts
replicas:
  - name: myapp
    count: 5

# Annotations transformer: add annotations
annotations:
  - includeSelectors: false
    pairs:
      contact: ops@example.com

Transformers are automatic transformations:

• images — rewrite image names and tags without patching the Deployment directly.
• replicas — set replica counts without patching.
• annotations — add annotations to all resources.

The advantage of transformers over patches: the manifest is unchanged; the transformer applies the change at render time. This keeps the base clean.

Generators

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

resources:
  - deployment.yaml

# ConfigMap generator
configMapGenerator:
  - name: app-config
    files:
      - config/app.properties
      - config/logging.properties
    envs:
      - config/env.properties
  - name: app-flags
    literals:
      - FEATURE_X=true
      - FEATURE_Y=false

# Secret generator (base64 encoded)
secretGenerator:
  - name: db-credentials
    literals:
      - username=admin
      - password=secretpassword
    type: Opaque

Generators create ConfigMaps and Secrets:

• configMapGenerator — from files, env files, or literal key-value pairs.
• secretGenerator — from literal key-value pairs (base64-encoded).

Generators are useful for keeping configuration files in version control without hardcoding them in the manifest.

Components

# components/monitoring/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

resources:
  - service-monitor.yaml
  - prometheus-rule.yaml

labels:
  - includeSelectors: false
    pairs:
      monitoring: enabled

# overlays/prod/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

resources:
  - ../../base

components:
  - ../../components/monitoring

Components are reusable kustomizations that can be included in multiple overlays. They add resources (common across overlays) without modifying the base.

Quiz

The operational discipline

kustomization.yaml in production rests on five non-negotiable elements:

• Use transformers over patches when possible. Transformers keep the base clean; patches are for complex changes.
• Use generators for ConfigMaps and Secrets. Keeps configuration in version control; hashes trigger rollouts.
• Use components for reusable resources. Monitoring, logging, and other add-ons that are common across overlays.
• Pin image tags explicitly. Never use floating tags (:latest, no tag) in production.
• Render before apply. Always verify the rendered output.

The kustomization.yaml is the heart of Kustomize. The discipline is to use the right field for the right task and to keep the base clean.