Kubernetes Kustomize Metadata Management

Kubernetes Kustomize Metadata Management is the practice of applying labels and annotations uniformly across every resource in a Kustomize build through the commonLabels, commonAnnotations, and newer labels transformers, including the critical distinction between transformers that also modify immutable selector fields and those that affect only descriptive metadata.

commonAnnotations

Uniform, Selector-Safe Metadata

commonAnnotations:
  managed-by: kustomize
  team: platform

commonAnnotations adds the given key-value pairs to every resource's metadata.annotations in the build, with no interaction with selector fields at all, since annotations are never used for object selection; this makes it unconditionally safe to apply broadly without risk of breaking selector matching anywhere in the build.

commonLabels and Its Selector Interaction

Labels Applied Everywhere, Including Selectors

commonLabels:
  environment: production

Unlike annotations, commonLabels (the older, still-supported transformer) applies the given labels not only to metadata.labels but also injects them into every selector field that references those labels, spec.selector on a Deployment or Service, spec.template.metadata.labels, and equivalent fields elsewhere, ensuring the selector and the labeled objects it must match remain consistent.

The Immutable Selector Hazard

Because a Deployment's spec.selector field is immutable after creation, applying commonLabels to an already-running resource in a way that changes the computed selector (adding a new common label to a base that previously had none, for instance) produces a rendered manifest that the API server will reject on update, since the selector cannot be changed in place; this specific hazard is one of the most common Kustomize-related deployment failures encountered in practice.

kubectl apply -f rendered.yaml
# error: Deployment.apps "web" is invalid: spec.selector: Invalid value: ...: field is immutable

The labels Transformer as the Modern Replacement

Explicit Control Over Selector Inclusion

labels:
  - pairs:
      environment: production
    includeSelectors: false
    includeTemplates: true

The newer, unified labels field replaces commonLabels with explicit includeSelectors and includeTemplates flags, letting an author apply a label to metadata.labels and, if desired, to pod template labels, while deliberately excluding it from spec.selector, directly avoiding the immutable-selector hazard that commonLabels could not prevent.

labels:
  - pairs:
      cost-center: platform-eng
    includeSelectors: false
    includeTemplates: false

Setting both flags to false applies a label purely as descriptive metadata on the top-level object, equivalent in effect to what commonAnnotations provides for annotations, giving fine-grained control per label group rather than a single all-or-nothing behavior.

Multiple Label Groups With Different Scopes

Combining Selector-Safe and Selector-Affecting Labels

labels:
  - pairs:
      app.kubernetes.io/part-of: myapp
    includeSelectors: true
  - pairs:
      cost-center: platform-eng
      owner: platform-team
    includeSelectors: false

Because labels accepts a list of independently configured groups, a single kustomization can apply one set of labels that genuinely needs to participate in selector matching alongside a separate set of purely informational, non-selector labels, a level of granularity commonLabels alone never offered.

Annotations and Labels From Generators

Generator Options Affecting Metadata

configMapGenerator:
  - name: app-config
    literals:
      - LOG_LEVEL=info
generatorOptions:
  labels:
    generated-by: kustomize
  disableNameSuffixHash: false

generatorOptions lets metadata (labels, annotations) be applied specifically to objects produced by configMapGenerator and secretGenerator, distinct from commonLabels/labels, which apply cluster-wide across every resource in the build regardless of origin.

Verifying Metadata Application

Confirming Correct Propagation

kustomize build overlays/production | yq 'select(.kind=="Deployment") | .spec.selector'

Given the selector-immutability hazard specific to label propagation, inspecting the rendered spec.selector directly after any change to commonLabels or labels configuration is a necessary verification step before applying the result to a cluster with existing running Deployments, rather than trusting the source configuration's apparent correctness alone.

Relationship to Package Resource Organization and Name Management

Metadata management complements the naming conventions covered under package resource organization and works alongside the reference-fixup mechanism described under name management: labels and annotations applied consistently are what make label-based querying (kubectl get all -l ...) reliable across an entire package, while the selector-immutability distinction between commonLabels and the newer labels transformer is one of the sharper edges in the Kustomize package model that must be understood to avoid breaking already-running resources during a routine metadata change.