Support structured-data traversal in nameReference transformer

[rbcb-dev]

Eschewed features

• This issue is not requesting templating, unstuctured edits, build-time side-effects from args or env vars, or any other eschewed feature.

What would you like to have added?

Please add support for nameReference to traverse and update references inside structured data embedded in scalar string fields, similar to the structured-data support that replacements gained in kustomize v5.8.0.

Today nameReference works on normal manifest fields selected via fieldSpecs, but it does not appear to descend into JSON/YAML stored inside fields such as:

• ConfigMap.data["config.yaml"]
• ConfigMap.data["config.json"]
• Secret.stringData[...]
• annotations or other scalar string fields that contain structured YAML/JSON

The feature request is that nameReference should be able to:

1. detect when a selected field is a scalar string containing YAML or JSON,
2. traverse into that structured content,
3. update the referenced name there,
4. serialize the content back while preserving format as much as possible.

Why is this needed?

A common use case is generated names from secretGenerator / configMapGenerator, especially hash suffixes.

We want the same nameReference semantics that already work for normal manifest fields to also work when the reference is embedded inside structured config data.

Example motivation:

• a Secret is generated by secretGenerator
• its final name gets a hash suffix
• another resource embeds that secret name inside ConfigMap.data["config.yaml"]
• nameReference should update the nested structured field so the generated hashed name is used there too

This would make it possible to propagate generated names consistently into application config stored inside ConfigMaps/Secrets, instead of only into top-level Kubernetes manifest fields.

Can you accomplish the motivating task without this feature, and if so, how?

Only with awkward workarounds:

• duplicate / patch whole embedded config documents
• use replacements for individual values
• avoid nameReference and manage generated names manually

Those workarounds lose the main benefit of nameReference: automatically following renamed resources, including generated hash suffixes.

What other solutions have you considered?

• Using replacements for individual structured-data values
• Duplicating full config documents per overlay
• Avoiding generated hash suffixes

Anything else we should know?

This seems closely related to the structured-data work already done for replacements in v5.8.0.

A possible implementation direction would be to generalize the structured-data path handling used by replacements so nameReference (and potentially other field-based transformers) can reuse it.

I am intentionally not prescribing the exact path syntax, but the desired outcome is:

• normal nameReference behavior for regular fields remains unchanged
• when a selected field is a scalar containing YAML/JSON, nameReference can descend into it and update nested references there too

Example

Input

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

resources:
  - app-configmap.yaml

secretGenerator:
  - name: app-credentials
    literals:
      - username=demo
      - password=demo

configurations:
  - nameReference.yaml

# app-configmap.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: app-settings
data:
  config.yaml: |
    auth:
      secretName: app-credentials

Conceptually, we want nameReference to be able to update the nested auth.secretName inside data["config.yaml"].

Expected output

apiVersion: v1
kind: Secret
metadata:
  name: app-credentials-<hash>
type: Opaque
...
---
apiVersion: v1
kind: ConfigMap
metadata:
  name: app-settings
data:
  config.yaml: |
    auth:
      secretName: app-credentials-<hash>

Thanks!

Feature ownership

• I am interested in contributing this feature myself! 🎉

[k8s-ci-robot]

This issue is currently awaiting triage.

SIG CLI takes a lead on issue triage for this repo, but any Kubernetes member can accept issues by applying the triage/accepted label.

The triage/accepted label can be added by org members by writing /triage accepted in a comment.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

[rbcb-dev]

Possible configuration shape

It would make sense to support this in the same way structured data is already handled for replacements, instead of introducing a separate syntax just for nameReference.

Example:

nameReference:
  - kind: Secret
    fieldSpecs:
      - kind: ConfigMap
        path: data.config\.yaml.auth.secretName

Given:

apiVersion: v1
kind: ConfigMap
metadata:
  name: app-settings
data:
  config.yaml: |
    auth:
      secretName: app-credentials

nameReference should update the nested auth.secretName inside data["config.yaml"] to the generated Secret name, including the hash suffix.

The same should also work for embedded JSON.

This would keep the behavior aligned with replacements and avoid having two different ways of addressing structured YAML/JSON content stored in scalar fields.