Kubernetes Kustomize Generator Management

Kubernetes Kustomize Generator Management is the practice of producing ConfigMap and Secret objects from external data sources through Kustomize's built-in generators, covering literal, file, and environment-file input sources, the merge behaviors that let an overlay extend rather than fully replace a base's generated content, and the extensibility mechanism for writing entirely custom generators beyond the two built-in kinds.

Input Sources for Generators

Literals, Files, and Env Files

configMapGenerator:
  - name: app-config
    literals:
      - LOG_LEVEL=info
      - MAX_CONNECTIONS=100
    files:
      - app.properties
      - nginx.conf=custom-nginx.conf
    envs:
      - config.env

literals inlines key-value pairs directly in kustomization.yaml; files reads the content of an external file, using the filename as the key unless an explicit key=path mapping is given; envs reads a file formatted as one KEY=value pair per line, treated as a batch of literals sourced from a separate file rather than duplicated inline.

Secret Generators and Type-Specific Behavior

Generic Secrets

secretGenerator:
  - name: db-credentials
    literals:
      - username=app_user
    files:
      - password.txt

secretGenerator mirrors configMapGenerator's input sources but produces a Secret object, base64-encoding the resulting data automatically, and is the standard way to generate credential-bearing objects without checking raw secret material into the same manifest tree in unencoded form.

Specialized Secret Types

secretGenerator:
  - name: registry-creds
    type: kubernetes.io/dockerconfigjson
    files:
      - .dockerconfigjson=docker-config.json
  - name: tls-cert
    type: kubernetes.io/tls
    files:
      - tls.crt=cert.pem
      - tls.key=key.pem

Setting an explicit type produces a correctly structured docker-registry pull secret or tls secret rather than the generic Opaque type, matching the exact key names (tls.crt, tls.key, .dockerconfigjson) that consuming resources such as imagePullSecrets or ingress TLS configuration expect.

Combining Generators Across Base and Overlay

The behavior Field

# overlay kustomization.yaml
configMapGenerator:
  - name: app-config
    behavior: merge
    literals:
      - LOG_LEVEL=debug

Setting behavior: merge on an overlay's generator entry combines its data with the base's generator entry of the same name, letting an overlay override or add specific keys without needing to restate every key the base already defines; behavior: replace instead discards the base's data entirely in favor of the overlay's, and behavior: create (the default when no matching base generator exists) produces an entirely new object.

Hash Suffix Behavior

Content-Based Immutability

configMapGenerator:
  - name: app-config
    literals:
      - LOG_LEVEL=info
    options:
      disableNameSuffixHash: false

By default, a generated ConfigMap or Secret receives a content-derived hash suffix in its name, and any Deployment referencing it by the pre-hash name is automatically rewritten (via the same reference fixup mechanism covered under name management) to reference the hash-suffixed name, guaranteeing a rolling update whenever the generated content changes.

Disabling the Hash for Stable Names

options:
  disableNameSuffixHash: true

Setting disableNameSuffixHash: true is appropriate when an external system outside the kustomization needs to reference the generated object by a stable, predictable name, trading away the automatic rollout-on-change guarantee for name stability.

Custom Generators via KRM Functions

Extending Beyond the Two Built-In Kinds

generators:
  - generator-config.yaml

apiVersion: example.com/v1
kind: RandomPasswordGenerator
metadata:
  name: db-password
spec:
  length: 24

Kustomize's plugin mechanism, based on the Kubernetes Resource Model (KRM) function specification, lets a generator be implemented as an external executable or container image that receives a specification object and emits generated resources, extending generation to arbitrary custom logic (random password generation, certificate issuance) beyond what configMapGenerator and secretGenerator alone provide.

kustomize build --enable-alpha-plugins overlays/production

Verifying Generated Output

Inspecting the Rendered Result

kustomize build overlays/production | yq 'select(.kind=="ConfigMap" and .metadata.name | test("app-config"))'

Because generated names include a computed hash suffix, confirming both the generated object's final name and its actual data content directly from rendered output, rather than assuming correctness from the generator's source configuration, is standard practice before applying, particularly after a merge-behavior change between base and overlay.

Relationship to Kustomize Patch and Name Management

Generator management operates alongside patch management and name management as the third major Kustomize customization mechanism: where patches modify existing resources and name transformers adjust identifiers uniformly, generators are the mechanism specifically for producing ConfigMap and Secret content from external, often environment-specific, data sources, with the merge-behavior and hash-suffix mechanisms determining how that generated content composes across a base-and-overlay hierarchy without manual key-by-key reconciliation.