In a Helm chart, how do you design escape hatches like extraEnv and podAnnotations?

### Why charts grow escape hatches at all No chart author can enumerate every field a consumer will need. A team needs one extra environment variable, a toleration for a tainted node pool, an annotation their platform reads, a sidecar's volume mount. Without a hatch, each of those turns into either a pull request against your chart or a fork of it, and a fork is the worst outcome: it never comes back, and it silently stops receiving your fixes. The hatch is the pressure valve that keeps consumers on your chart. ### The rendering mechanics Every hatch is rendered the same way: ```yaml spec: {{- with .Values.nodeSelector }} nodeSelector: {{- toYaml . | nindent 8 }} {{- end }} ``` Three pieces matter. `toYaml` serialises whatever the user supplied back into YAML, so you never have to know its shape. `nindent N` prefixes a newline and indents every line by N spaces - the plain `indent` leaves the first line glued to the pipeline's position and produces broken YAML, which is why `nindent` is the one you see in real charts. And `with` sets the dot to the value and skips the block entirely when it is empty, so an unedited install does not emit `nodeSelector:` with nothing beneath it. Getting the `nindent` count wrong is the single most common defect here; the count is the indentation of the *children*, not of the key. If you want users to be able to write `{{ .Release.Name }}` inside a hatch value, pass the serialised block through Helm's `tpl` function before rendering it. That is a real feature and occasionally necessary, but say so in the documentation: from that moment on, a value containing braces is evaluated rather than taken literally, which will surprise someone eventually. ### Map or list is the real design decision Helm coalesces maps key by key and replaces lists outright. That single rule decides how your hatch behaves under layering. - `podAnnotations: {}` as a map: a platform base values file can set two entries, a team's file adds a third, and all three land. Additive by construction. - `extraEnv: []` as a list of Kubernetes environment-variable objects: whichever file is applied last supplies the entire list. The platform's entries silently vanish when a team adds one of their own. Neither is wrong, but the trade must be conscious. The list shape wins on fidelity - it is exactly the upstream schema, so a user pastes an entry with a `valueFrom` reference straight from the platform documentation and it works. The map shape wins on composition. Some charts offer both: a `extraEnv` list for full-fidelity entries and a simple `env` map of name-to-value for the common case that composes. That is two keys to support forever, so only do it where the demand is real. The same logic applies to every hatch: `podAnnotations` and `podLabels` and `nodeSelector` are maps and compose; `tolerations`, `extraVolumes`, `extraVolumeMounts`, `initContainers` and `extraContainers` are lists and do not. Volume hatches come in pairs and should be named as an obvious pair, because a volume without its mount is a silent no-op. ### The last-resort hatch Some charts offer `extraObjects`: a list of raw manifests, usually rendered through `tpl`, that Helm installs as part of the release. It is the ultimate valve - a team can add a resource kind your chart never contemplated without forking - and it is genuinely useful for a monitoring-stack chart whose three subcharts each need a companion object. It is also a hole in every promise the chart makes, because nothing in your templates inspects what comes through it. If you ship one, know that those objects are part of the release like any other: they are stored in the release record, upgraded with it, and removed on uninstall. Pair it with a cluster-side control - an admission policy engine, applied to everything regardless of how it arrived - rather than trying to police it in templates. ### What to tell consumers Document, in `values.yaml` comments beside the key, three things: that the block is rendered verbatim, whether it merges or replaces, and what the chart itself already puts in the same place. That last point is the one people trip on - if your chart sets its own annotations on the same object, a consumer needs to know whether their entries and yours coexist. Where a chart-owned entry must win, build a map of your entries and merge the user's underneath it, so an override cannot quietly displace something the chart is responsible for.