chartutil: add Literal mode to ValuesReference (helm --set-literal semantics)

[gecube]

Problem

When a HelmRelease consumes a ConfigMap or Secret via valuesFrom with a targetPath set, the referenced value is currently passed to Helm's strvals.ParseInto — the same parser as helm --set. That treats ,, [, ], {, }, = and \ in the value as syntactic metacharacters, so arbitrary file content (Spring application.yml with flow sequences, HOCON application.conf, JSON blobs, multi-line YAML with trailing commas, …) is misparsed or fails outright with errors like:

error parsing index: strconv.Atoi: parsing " \"prometheus\", \"health\", \"info\" ": invalid syntax

key "efm" has no value (cannot end with ,)

The single/double-quote workaround introduced in helm-controller#298 ('<value>' → ParseIntoString) is impractical for delivering raw config files via kustomize configMapGenerator / secretGenerator: the generated CM data is the file content as-is, with no opportunity to wrap it without sidecar files or build steps. Flux's kustomize-controller explicitly disables Kustomize plugins (PluginConfig: kustypes.DisabledPluginConfig()), so a transformer-based workaround isn't available either.

Solution

Adds a Literal bool field to meta.ValuesReference. When Literal: true together with TargetPath, ChartValuesFromReferences calls a new ReplacePathLiteralValue helper instead of ReplacePathValue. The helper pre-escapes strvals metacharacters in the value, then delegates to strvals.ParseIntoString — that combination yields:

• Value preserved verbatim (no ,/[/{/= interpretation; no type coercion to int/bool/list/map).
• Path escapes still honoured (externalConfig.application\.yml.content resolves to the literal key application.yml, which the alternative strvals.ParseLiteralInto does not).

Literal has no effect when TargetPath is empty (the root YAML-merge path is unchanged). Default Literal: false is fully backward compatible.

Why not strvals.ParseLiteralInto?

It is the obvious choice and was the first thing I tried. It correctly preserves value metacharacters, but does not support \. escapes in the path:

externalConfig.application\.yml.content=hello
  → ParseIntoString:   externalConfig.application.yml.content = "hello"   ✓
  → ParseLiteralInto:  externalConfig["application\"]["yml"]["content"] = "hello"   ✗

Charts that use filenames as map keys (a common Helm pattern for per-file config) need the \. escape, so I went with pre-escaping the value and routing through ParseIntoString. Documented in the function doc comment.

API

spec:
  valuesFrom:
    - kind: ConfigMap
      name: my-service-config
      valuesKey: application.yml
      targetPath: 'externalConfig.application\.yml.content'
      literal: true   # NEW

Tests

chartutil/values_test.go gains:

• TestChartValuesFromReferences — new cases:
  • non-literal target path mangles value with commas — pinning the current bug as a regression test.
  • literal target path preserves helm-set metacharacters — Spring-style YAML with flow sequence.
  • literal target path preserves multi-line HOCON with equals and braces — HOCON content read from a Secret.
  • literal flag without targetPath is ignored (root YAML merge) — documents the no-effect branch.
• TestReplacePathLiteralValue — 10 unit cases covering commas, braces, brackets, equals, multi-line YAML, HOCON, JSON, boolean-shaped strings, and the \. path escape.

All existing tests continue to pass.

Backward compatibility

• New optional field with omitempty; defaults to false.
• DeepCopy is a no-op (*out = *in) — ValuesReference is a plain value type, no regeneration needed.
• Existing references behave identically (call site path picks ReplacePathValue when Literal: false).

Follow-up

This PR ships the API + behaviour in fluxcd/pkg. A follow-up PR in fluxcd/helm-controller will:

1. Bump the fluxcd/pkg dependency to a release containing this change.
2. Regenerate config/crd/bases/helm.toolkit.fluxcd.io_helmreleases.yaml so the field is openAPI-validated by the API server.
3. Add a valuesFrom literal section to docs/spec/v2/helmreleases.md.

Related

• Resolves fluxcd/helm-controller#1317 (request for --set-literal semantics in valuesFrom + targetPath)
• Addresses parts of #460 (YAML / raw value in valuesFrom)
• Practical examples discussed in #853, flux2#1756, where users hit the manual-escape wall.
• Helm landed --set-literal upstream in helm#9182 (v3.12); this brings the equivalent to Flux.