Redesign manager env values in helm/v2-alpha

History

manager.env is scaffolded as a list, because Kubernetes container env is a list and entries can carry valueFrom.

#5489 reported that this is unergonomic:

users at install time cannot just --set manager.env.SOMEVAR=true (because manager.env is not a dict, it's a list), they need to set the whole manager.env, duplicating the whole list

#5495 answered with a second key, manager.envOverrides, a map that is merged over the list at render time. env stayed a list so it could keep carrying valueFrom. No alternative shape was discussed at the time.

#5948 then reported that envOverrides produces duplicate env.name entries, which Server-Side Apply rejects. The variable that broke was WATCH_NAMESPACE, which we scaffold as a fieldRef — the user was pinning it to a literal namespace.

#5949 proposes to fix the duplicate by merging by name, and to reject any override name that is not already in manager.env. That last part reverses what #5489 asked for.

Problem

The list plus override-map shape is the root cause, not the merge logic on top of it:

• Duplicate env.name breaks Server-Side Apply (#5948).
• There is no way to remove a variable the chart scaffolded.
• It is unclear whether an override may add a variable or only change one. #5489 wanted add, #5949 forbids it.
• A numeric value renders as value: 8080, which the API rejects.
• Any rule like "an override cannot touch a valueFrom entry" would block the exact case reported in #5948.

Possible solution

Make manager.env a map and drop envOverrides. A scalar value becomes value, a map value becomes valueFrom.

manager:
  ## Add, change or remove one with --set manager.env.NAME=value
  env:
    BUSYBOX_IMAGE: busybox:1.36.1
    MEMCACHED_IMAGE: memcached:1.6.26-alpine3.19
    WATCH_NAMESPACE:
      fieldRef:
        fieldPath: metadata.namespace

Helm merges maps natively, so no merge logic stays in the template. Duplicate names become impossible because map keys are unique.

Built into the testdata chart and rendered with helm v3.18.1:

Open question. Map keys are unordered, so the render sorts alphabetically and the authored order is lost. Kubernetes expands $(VAR) only against earlier entries, so URL=$(HOST):$(PORT) could break silently. This is the tradeoff to decide.

Note. This is a breaking change. The plugin is alpha and the bug has existed since v4.14.0, so there is no rush to patch the symptom first.

References

• #5489 — original request, --set manager.env.SOMEVAR=true
• #5495 — added manager.envOverrides
• #5948 — duplicate env.name breaks Server-Side Apply
• #5949 — proposed fix, blocked by this issue