What do the three values of Helm's helm.sh/hook-delete-policy do, and which applies when it is omitted?

### The annotation and its grammar `helm.sh/hook-delete-policy` is read only on a manifest that also carries `helm.sh/hook`; on an ordinary chart resource it is inert metadata that Helm ignores. Its value is a comma-separated list, so several policies can be in force at once: ```yaml annotations: "helm.sh/hook": pre-upgrade "helm.sh/hook-delete-policy": before-hook-creation,hook-succeeded ``` Three values are defined, and each names a different moment in the hook's life. **`before-hook-creation`** fires just before Helm creates that hook resource. Helm deletes an existing object of the kind and name the hook manifest declares, waits for it to actually be gone, and then creates the new one. Nothing exists to delete on a first install, and that is not an error — the run simply proceeds. This is the policy that makes a hook with a stable, deterministic name re-runnable across upgrades. **`hook-succeeded`** fires after the hook has completed and Helm has judged it successful. The object is deleted before Helm moves on to the rest of the release. **`hook-failed`** fires after the hook has completed and Helm has judged it failed. The object is deleted even though the release is about to abort. ### The default, and the trap inside it If the annotation is absent, Helm applies `before-hook-creation`. That is the single most useful fact about the annotation, and its consequence is the trap: the default applies only when the policy list is *empty*. The moment you write any value, you have replaced the default rather than added to it. A chart that sets `helm.sh/hook-delete-policy: hook-succeeded` — a very natural thing to write, meaning "tidy up after a good run" — has silently switched off the pre-creation delete. Successful runs clean themselves; the first failed or interrupted run leaves an object sitting on the hook's name, and there is no longer anything to clear it before the next attempt. If you want both behaviours, both must be listed. ### What the policy does not do It does not govern the release's ordinary resources; those are managed through the release manifest and are upgraded and deleted with it. It does not roll anything back: `hook-failed` deletes the hook object, it does not undo work the hook already did, and it has no bearing on whether the release aborts. It does not extend to objects the hook's own process creates at runtime, which Helm never sees. And it does not protect anything — there is no "keep" value in this annotation's vocabulary; keeping is what happens when no policy matches the outcome. ### Choosing the combination Three combinations cover almost every real chart. `before-hook-creation,hook-succeeded` is the workhorse: a clean rerun every time, no accumulation of completed objects, and the failed object left in place so its Pods and logs can be read. Bare default (`before-hook-creation`) suits a hook whose artefact you want to inspect after every run, at the price of one lingering object per hook. Adding `hook-failed` on top gives the tidiest namespace and is right for a hook that already ships its own diagnostics elsewhere, but it is the choice that removes the evidence in an incident, so make it deliberately rather than by copying a template. ### A detail worth carrying The deletion is targeted by what the hook manifest names — its kind and its name — not by a search for objects Helm previously created. That is another argument for release-scoped hook names built from `.Release.Name`: a hook called `db-migrate` in a shared namespace tells Helm to delete whatever `db-migrate` is currently there, which in a multi-tenant namespace may not be the object you had in mind. It is also why `before-hook-creation` is so effective for run-to-completion work: the object it deletes is by definition the previous incarnation of the same hook. ### Reading it back from a live release The annotations that matter are the ones on the *rendered* hook, not the ones in the chart source you happen to be looking at, and values or conditionals may differ between the two. `helm get hooks <release>` prints the hook manifests exactly as they were recorded for that release, annotations included, which is the fastest way to settle an argument about which policy a given deployment actually has in force.