Kubernetes Kustomize Name Management

Kubernetes Kustomize Name Management is the practice of using Kustomize's namePrefix, nameSuffix, and namespace transformers to adjust resource names and namespaces uniformly across an entire package, relying on Kustomize's built-in reference-fixup mechanism to automatically update every field elsewhere in the same build that refers to a renamed object by name.

Prefix and Suffix Transformers

Applying a Uniform Prefix

namePrefix: prod-
resources:
  - deployment.yaml
  - configmap.yaml

kustomize build overlays/production | grep "name:"
# name: prod-web
# name: prod-app-config

namePrefix (and its counterpart nameSuffix) is applied to every resource's metadata.name in the build, letting multiple environments or tenants share an identical base while remaining distinguishable and non-colliding when deployed into the same namespace or cluster.

Automatic Reference Fixup

Why References Do Not Break

# base deployment.yaml
spec:
  template:
    spec:
      containers:
        - envFrom:
            - configMapRef:
                name: app-config

kustomize build overlays/production
# configMapRef:
#   name: prod-app-config

When namePrefix renames app-config to prod-app-config, Kustomize also rewrites every recognized reference field elsewhere in the build, configMapRef.name, secretRef.name, volume configMap.name, serviceAccountName, and dozens of other well-known reference fields, so that the renamed object and everything pointing to it remain consistently linked without any patch author needing to manually update reference fields themselves.

The Fixed Reference Field List Is Built-In, Not Automatic Reflection

Kustomize's reference fixup works from an internal, maintained list of known reference field paths per resource kind, not from any generic reflection over arbitrary fields; a custom resource with its own field referencing another object by name (a CRD's spec.configMapRef.name, for instance) is not automatically fixed up unless Kustomize has been explicitly configured, via a configurations file, to recognize that field as a name reference.

# nameReference.yaml
nameReference:
  - kind: ConfigMap
    fieldSpecs:
      - path: spec/configMapRef/name
        kind: PostgresCluster

configurations:
  - nameReference.yaml

Namespace Transformer

Uniform Namespace Assignment and Fixup

namespace: production

The namespace transformer sets metadata.namespace on every namespaced resource in the build and simultaneously fixes up any RoleBinding or other cross-referencing object's namespace field that must match, ensuring an overlay's namespace choice propagates consistently rather than requiring every resource and every reference to be patched individually.

Interaction with Hash-Suffixed Generated Names

Prefix, Suffix, and Content Hash Together

namePrefix: prod-
configMapGenerator:
  - name: app-config
    literals:
      - LOG_LEVEL=info

kustomize build overlays/production | grep name:
# name: prod-app-config-8f92hc4gtb

A ConfigMap or Secret produced by a generator receives both the overlay's namePrefix and its own content-hash suffix, and Kustomize's reference fixup correctly resolves any consumer's reference to the fully composed final name, chaining the prefix transformer and the generator's hash suffix together transparently.

Common Pitfalls

Cross-Kustomization References Are Not Fixed Up

# overlay A references a ConfigMap that overlay B renamed independently

Reference fixup operates only within a single kustomize build invocation; if two separately built kustomizations need to reference each other's renamed resources (a ConfigMap produced by one Kustomization consumed by a Deployment in an entirely separate one), no automatic fixup occurs across that boundary, and the consuming manifest must reference the exact final name manually or via some other coordination mechanism.

Hardcoded Names Bypassing Fixup

# anti-pattern: a raw string reference that Kustomize cannot recognize as a name reference
env:
  - name: CONFIG_NAME
    value: "app-config"

A reference expressed as an opaque string value passed to an application (rather than in a field Kustomize recognizes as a Kubernetes object name reference) is never rewritten by name management transformers, since Kustomize has no way to know that string represents an object name at all; such references require a configMapGenerator-based variable substitution or a manually maintained patch instead.

Relationship to the Kustomize Package Model and Resource Organization

Name management is one of the built-in transformers that gives the Kustomize package model its practical value beyond simple resource concatenation, and it directly supports the naming conventions discussed under package resource organization: consistent, automatically fixed-up prefixes and namespaces are what let a single base be deployed multiple times, side by side, without name collisions or manually maintained cross-references breaking silently.