What does the helm.sh/resource-policy: keep annotation do to a rendered resource?

### The annotation ```yaml metadata: annotations: helm.sh/resource-policy: keep ``` It is read by Helm, not by Kubernetes — nothing in the cluster changes behaviour because of it. It is a marker on a rendered object that Helm consults whenever it is about to issue a delete for that object. ### When Helm would otherwise delete There are two distinct situations, and candidates usually name only the first: 1. **Uninstall.** Helm walks the stored manifest of the current revision and deletes each object in it. An object annotated `keep` is skipped. 2. **An upgrade (or rollback) that drops the object.** When the newly rendered manifest no longer contains an object that the previous revision's manifest did — the template was deleted, or a conditional turned it off — Helm deletes it as part of reconciling to the new state. `keep` skips that deletion too. The second case is the one people are surprised by, in both directions: surprised that a template they removed took a live object with it, and surprised that annotating it `keep` means that object now hangs around forever after they thought they had removed the feature. ### What the survivor becomes The kept object is not transferred to some other manager; it is simply not deleted. It keeps whatever labels and annotations it was rendered with, including `app.kubernetes.io/managed-by: Helm` and the release metadata — which is now a lie, because the release that put them there may no longer exist. Nothing tracks it, nothing will update it, and no future `helm upgrade` will touch it, because it is not in any release's manifest any more. That produces the second-order problem. Install the same chart again into the same namespace and Helm renders the same object, finds one already present, and sees ownership metadata pointing at a release that is not this one. Helm refuses to adopt objects it does not own, so the install fails on an existing resource rather than quietly taking it over. The candidate who has actually operated this will say so unprompted: `keep` converts a data-loss risk into a redeploy-collision risk, and someone has to own the resulting cleanup. ### What to annotate, and what not to The rule of thumb is that `keep` belongs on objects whose deletion is unrecoverable, and nowhere else: - a PersistentVolumeClaim the chart renders directly, holding data the chart cannot regenerate; - a CRD rendered under `templates/` (as opposed to shipped in `crds/`), because deleting a CRD takes every custom resource of that kind with it, cluster-wide; - occasionally a Secret whose value was generated once at install time and is not reproducible. It does not belong on Deployments, Services, ConfigMaps, ServiceAccounts or anything else the chart can simply re-render. Annotating those makes uninstall a lie: the release disappears from `helm list` while most of the workload is still running, and the next engineer has to reconstruct by hand what the release used to consist of. ### Making the survivors visible Because `keep` is invisible at operation time unless you go looking, treat it as a chart-review concern. Grep the rendered output rather than the templates, since the annotation may be conditional: ```bash helm get manifest platform-core -n platform | grep -B8 'helm.sh/resource-policy: keep' ``` That tells you, before you run an uninstall, exactly which objects will still be in the namespace afterwards — and it is the difference between a teardown you can verify and one you merely hope worked. ### The boundary worth stating `keep` is a chart-author decision expressed in the chart, and it applies to objects Helm renders. It has nothing to say about objects Helm never rendered in the first place: claims a controller created from a StatefulSet's volume claim templates, or CRDs installed from `crds/`, survive uninstall regardless of any annotation, because Helm was never going to delete them. Confusing the two is the most common way this topic goes wrong in an interview: `keep` is the reason a *tracked* object survives, not the explanation for every leftover in the namespace.