Introduction

This Kustomize issue usually appears when secretGenerator creates a hashed Secret name, but a workload still references the unhashed base name through envFrom.secretRef.name. The generator is usually not the problem. The real issue is that name-reference transformation did not hit the field you expected, or a later patch overwrote the transformed result.

Why the Secret Name Changes

By default, secretGenerator adds a content hash to the generated name. That behavior is intentional because it helps create a new resource identity when the secret contents change.

1secretGenerator:
2  - name: app-config
3    literals:
4      - DB_URL=postgres://db
5      - DB_USER=app

At build time, that may become something like app-config-7f9c2t6g8m. If the workload still points at app-config, pod startup fails because the referenced Secret does not exist.

Kustomize Must Know a Field Is a Secret Reference

Kustomize can rewrite many well-known reference fields automatically, but not every path is guaranteed in every composition style. If envFrom.secretRef.name is not getting updated, add an explicit name-reference configuration.

1# kustomizeconfig.yaml
2nameReference:
3  - kind: Secret
4    fieldSpecs:
5      - kind: Deployment
6        path: spec/template/spec/containers/envFrom/secretRef/name
7      - kind: StatefulSet
8        path: spec/template/spec/containers/envFrom/secretRef/name

Then reference that configuration:

configurations:
  - kustomizeconfig.yaml

This tells Kustomize that those fields should follow generated Secret names.

Watch Patch Order and Overrides

One of the most common causes is not missing transformation but a later patch putting the base name back.

For example, if a strategic merge patch says:

envFrom:
  - secretRef:
      name: app-config

then that patch can undo or bypass the transformed value depending on the build flow. The safe pattern is:

• keep base manifests on the logical unhashed name
• let secretGenerator create the hashed object
• let name-reference transformation rewrite consuming fields
• avoid patches that hardcode the final live name again

The rendered output is the truth, so inspect that before applying anything.

kustomize build overlays/prod | yq '.spec.template.spec.containers[].envFrom'

Disable the Hash Only If You Mean It

You can disable hashed suffixes:

generatorOptions:
  disableNameSuffixHash: true

That gives a stable Secret name, but it also removes one of the natural rollout triggers that changing generated names provides. If you turn the hash off, make sure you have another clear strategy for updating workloads when secrets change.

This is a design choice, not a harmless workaround.

Consider Modern Kustomize Patch Style

Older examples often use patchesStrategicMerge. Modern Kustomize also supports patches, which can be easier to reason about when overlays become more complex. The main point is not which patch syntax you choose. The main point is understanding that later patches can override transformed references.

If you keep hitting this issue, reduce the overlay to a smaller reproducer and inspect the exact rendered object. Kustomize problems are usually much easier to debug from the final build output than from mentally simulating the transform chain.

A Good Troubleshooting Checklist

When the secret reference is still wrong, check these in order:

1. inspect the kustomize build output
2. confirm the nameReference field path matches the resource shape exactly
3. check init containers and sidecars too, not only the first container list
4. verify no later patch rewrites the name back to the base value
5. confirm your Kustomize version behaves the way your examples assume

Most failures come from path mismatches or patch order, not from secretGenerator ignoring the hash logic.

Common Pitfalls

The biggest mistake is assuming every secret-reference path is rewritten automatically in every overlay pattern.

Another issue is hardcoding the final hashed name into a patch, which defeats the purpose of content-based generation and is fragile across content changes.

Teams also often disable the hash suffix as a quick fix without adding another rollout or refresh strategy for secret changes.

Finally, debugging Kustomize without looking at kustomize build output is mostly guesswork. Always inspect the rendered manifest.

Summary

• 'secretGenerator hash suffixes are expected behavior, not the underlying bug.'
• Problems usually come from missing name-reference transformation or later patch overrides.
• Register envFrom.secretRef.name explicitly when Kustomize does not rewrite that path automatically.
• Inspect final rendered output before applying overlays.
• Disable name hashing only if you deliberately choose a different secret-update strategy.