Why must a Helm chart's Deployment selector carry only a subset of the labels the chart emits?

## The two label sets A well-formed chart emits its metadata twice, in two different shapes, and the reason is entirely about mutability. The **full set** is what you want visible on every object: the chart artefact (`helm.sh/chart`), the application name and instance, the app version, and managed-by. It goes on `metadata.labels` of each rendered object and on the Pod template's labels. The **selector set** is a strict subset - conventionally `app.kubernetes.io/name` plus `app.kubernetes.io/instance`. It goes in `spec.selector.matchLabels` and nowhere else. The difference is that `name` and `instance` are fixed for the lifetime of a release, while `helm.sh/chart` embeds `.Chart.Version` and `app.kubernetes.io/version` embeds `.Chart.AppVersion`. Those two move constantly - a chart under active development changes version several times a week. ## Why moving labels in a selector is fatal `spec.selector` is immutable on Deployments, StatefulSets and DaemonSets. It is set at creation and the API server rejects any later change to it. Put `helm.sh/chart` in `matchLabels` and the chart installs perfectly. The failure arrives on the *next* upgrade that changes the chart version: the rendered selector differs from the stored one, the API server refuses the update because the field is immutable, and Helm reports the upgrade as failed. Nothing about the error mentions labels or charts - it names the immutable field - which is why candidates who have not hit it before struggle to trace it back to the selector. What makes this a genuinely bad bug is that there is no gentle fix. - **Rolling back** does not help: the stored selector is already the old one, and the *next* version bump fails the same way. The chart is broken, not the release. - **`helm upgrade --force-replace`** (its Helm 3 name `--force` survives as a deprecated alias) makes Helm replace the resource rather than patch it - a delete and recreate. That does clear the immutable field, at the cost of removing the object and every Pod behind it at once, with no rolling update. For a stateless workload behind a load balancer that is a hard outage; for a StatefulSet it is worse. - **Uninstall and reinstall** works and is honest, but it throws away the release history and has the same availability cost. So the discipline is preventive: fix the chart so the selector never has to change, then take the one-time replacement hit. ## The subset rule The Pod template's labels must be a *superset* of the selector: every key/value in `matchLabels` has to be present on the template, or the controller creates Pods it cannot then match. The reverse is not required - the template may carry many labels the selector ignores. That asymmetry is what lets the full set live on the Pod template while the selector stays minimal. It also means changing a version-bearing Pod template label is legal: it changes the Pod template, which triggers a rollout, but it does not touch the selector and so does not fail. ## The overrides trap The two selector labels are stable *by convention*, not by force. `app.kubernetes.io/instance` is `.Release.Name` and cannot change while the release exists. `app.kubernetes.io/name` derives from the chart name through a values key such as `nameOverride`. If a user sets or changes `nameOverride` on an already-installed release, the rendered selector changes and the upgrade fails on exactly the same immutable field. Treat name-shaping values as install-time-only, say so in the chart's documentation, and if you need a guard, a JSON-Schema or template check is cheaper than an outage. ## Adding a label later A related question: can you add a label to an existing selector? No. `matchLabels` immutability covers additions as well as edits - a selector with one more key is a different selector. If a chart genuinely needs a new selector key (say it never had `instance` and two releases are colliding), that is a replacement, planned deliberately, not something to slip into a routine upgrade. ## What good looks like A good answer states the immutability, names which emitted labels are volatile and why, and explains that the Pod template can carry them safely. A strong answer adds the recovery options with their real costs, and flags `nameOverride` on a live release as the same failure wearing a different hat.