Which changes to a published chart's values.yaml are breaking for consumers, and how do you ship one?

## The contract you are breaking A published chart's `values.yaml` is an API. Consumers write their own file against it, pin a chart version, and then upgrade. Whether a change is breaking has nothing to do with how large the diff is; it is decided by one question: **if a consumer upgrades with their existing values file unchanged, what happens?** Three answers are breaking. **1. It fails.** A key that used to be optional is now required, a type changed from a string to a list, or the chart gained a `values.schema.json` that rejects a file that used to work. This is the *best* kind of breaking change, because the consumer finds out at render time and nothing reaches the cluster. **2. It silently renders something different.** This is the one that causes incidents. Consider an `invoice-worker` chart that renders a Secret from a values key, and version 3.0.0 moves `smtpPassword` to `credentials.smtp.password`. Helm does not validate the shape of user-supplied values: unknown keys are merged into `.Values` and simply never read. So the consumer's `smtpPassword: ...` sits there being ignored, the Secret renders from the chart's default — empty or a placeholder — and the worker restarts with credentials that do not work. Nothing warned anybody. The same shape occurs when you change a *default*: flipping a default replica count, enabling a probe, or tightening a resource limit changes rendered output for every consumer who never set that key. **3. It forces a destructive upgrade.** Values that feed resource names or selector labels are load-bearing in a way ordinary values are not. Change the naming template and the upgrade deletes the old object and creates a new one — a fresh Deployment, an orphaned PersistentVolumeClaim, a new Service with a new cluster IP. Change something that lands in an immutable field, such as a Deployment's selector, and the API server rejects the update outright, leaving the release failed. By contrast, the safely non-breaking change is narrow: **adding a new optional key whose default reproduces the current rendered output exactly.** If the new key changes what an untouched install renders, it is not additive. ## Shipping one anyway Sometimes the rename is right. The technique has four parts. **Bump the major.** The chart version is the only signal consumers have. A breaking values change goes out as 3.0.0, never as 2.97.0, so anyone pinned to a range within 2.x is untouched until they choose to move. **Make the old key loud.** During the window where both are documented, read the removed key and abort with a message that names the replacement: ```yaml {{- if .Values.smtpPassword }} {{- fail "values key 'smtpPassword' moved to 'credentials.smtp.password' in chart 3.0.0" }} {{- end }} stringData: smtp-password: {{ required "credentials.smtp.password is required" .Values.credentials.smtp.password | quote }} ``` `fail` and `required` are both functions Helm adds on top of the standard template library. This converts the silent case into the failing case, which is the whole point — a failed `helm upgrade` at 09:00 is cheaper than a worker running with a broken credential. **Or bridge, then remove.** If a hard failure is too aggressive for the number of teams involved, accept both for one minor line — `{{ .Values.credentials.smtp.password | default .Values.smtpPassword }}` — and emit a deprecation warning through `NOTES.txt`, which prints on every install and upgrade. Then delete the bridge in the next major. The window is only useful if it actually closes. **Write it down where they will look.** The chart's README and `NOTES.txt` carry the migration; a values key rename with no upgrade note is a support ticket per consuming team. ## Verifying before you publish Before tagging the major, render the chart against the values files you know consumers use and diff the output against the previous version. Unexpected differences in object names, selector labels or Secret contents are exactly the class of change described above, and they are visible from a render alone — no cluster required. ## The judgement an interviewer is listening for A strong answer says the quiet part: the reason renames are expensive in Helm is that there is no compiler and no type check between your chart and someone else's values file. Nothing links them except a version number and a document. That is why the major bump, the loud failure and the written migration are not ceremony — they are the only mechanisms available.