Waleed edc25aa976 docs(helm): document null as the way to remove an inherited env key (#6801) ...

* docs(helm): document null as the way to remove an inherited env key

Setting `app.env.KEY: ""` cannot clear a key that `app.envDefaults` sets:
the Secret template drops empty values, and the deployment template treats
an empty override as "not overridden" and still inlines the default. Helm's
own `KEY: null` deletion is the supported mechanism and already works.

The empty-string behavior is load-bearing, not a bug — every key under
`app.env` ships as a "" placeholder, and ten collide with a real
`envDefaults` value (NEXT_PUBLIC_APP_URL, BETTER_AUTH_URL, ...), so "" has
to read as "unspecified" or a default install would blank them out.

- README: document `null`, with the --reuse-values and Argo CD valuesObject
  caveats; correct the claim that `app.env` always wins over `app.envDefaults`
- values.yaml + self-hosting docs: same guidance where operators look
- sim-helm skill: record why an unset list is the wrong shape here
- tests: lock in that null removes a key and "" does not

* docs(helm): correct the verify command's chart path and scope the required-secret claim

- The verify snippet used a `sim/sim` repo alias that this chart never
  publishes; every other instruction installs from the local `./helm/sim`
  path, so the command could not run as written
- Nulling a boot-critical key only fails at template time with the
  chart-managed Secret. `existingSecret` mode skips that validation
  entirely (the chart cannot read a pre-created Secret), and under ESO the
  key must instead be mapped in externalSecrets.remoteRefs.app

* docs(helm): say null must be applied in every layer that sets a key

`null` deletes a key from the map it is applied to, not from the pod. A key
set in both `app.env` and `app.envDefaults` survives a null on the app.env
entry alone — the deployment then inlines the envDefaults value again. Under
ESO a retained `externalSecrets.remoteRefs.app` mapping keeps syncing the key
regardless of app.env.

- README and self-hosting docs: drop the "works in all three secret modes"
  shorthand and spell out that every layer setting the key must be nulled,
  including the ESO remote mapping
- tests: cover both halves — nulling only app.env restores the envDefault,
  nulling both actually removes the key
- chart 1.5.4; staging took 1.5.3 in the meantime

2026-08-17 18:16:35 -07:00

..

docs

docs(helm): document null as the way to remove an inherited env key (#6801)

2026-08-17 18:16:35 -07:00