Hook Events

### What a hook actually is Everything under a chart's `templates/` directory renders to Kubernetes manifests. Helm normally gathers all of them into one document — the **release manifest** — and applies that document as a unit, storing it in the release record. A hook is the exception to that flow. Any rendered manifest carrying the annotation `helm.sh/hook` is lifted out of the release manifest before anything is applied and held in a separate hook list attached to the release, to be applied on its own at the lifecycle point the annotation names. ```yaml apiVersion: batch/v1 kind: Job metadata: name: {{ include "gateway.fullname" . }}-schema annotations: "helm.sh/hook": pre-upgrade spec: backoffLimit: 0 template: spec: restartPolicy: Never containers: - name: migrate image: registry.example.com/gateway-migrator:4.11.2 ``` Nothing else about the manifest is special. It is a normal Job that a normal cluster would accept; the annotation is the whole difference. ### The nine events The annotation's value is one of nine event names: `pre-install`, `post-install`, `pre-upgrade`, `post-upgrade`, `pre-rollback`, `post-rollback`, `pre-delete`, `post-delete` and `test`. The `pre-` events run after templates have been rendered but before Helm touches the cluster for that operation; the `post-` events run after all of the operation's resources have been applied. `test` is inert during install and upgrade and is applied only when someone runs `helm test` against the installed release. A value may list more than one event, comma-separated — `helm.sh/hook: post-install,post-upgrade` is the idiom for "run this every time the chart is deployed, first time or not". ### What Helm does when the event fires Helm applies the hook resource and then **blocks on it**. It waits until the resource reports ready — for a Job that means it completed successfully — before continuing to the rest of the operation. If the hook never gets there, the operation fails when the timeout expires. That wait is unconditional and is not the same knob as waiting for the chart's own workloads: in Helm 4 the `--wait` flag is strategy-valued and defaults to `hookOnly`, which is exactly this — Helm waits for hooks but not for your Deployments unless you ask for `watcher` or `legacy`. Helm 3's boolean `--wait` was off by default and also always waited on hooks. ### Hooks live outside the release manifest This is the part candidates miss, and it has consequences well beyond a CLI quirk. `helm get manifest <release>` prints the release manifest and will not show your hook; `helm get hooks <release>` prints the hooks that Helm stored for the current revision. Because an upgrade is computed by comparing release manifests, an object a hook created is never diffed, never patched, never pruned when it disappears from the chart, and never restored by `helm rollback`. Helm treats hooks as **one-shot actions**, not as managed state. A hook that creates a long-lived object is therefore creating an orphan the release does not own. ### Any kind can be a hook Job and Pod dominate because they run to completion and completion is a meaningful success signal. But the annotation is not restricted to them. A ConfigMap or Secret annotated `pre-install` is applied and considered ready immediately, which is how a chart seeds a credential a workload will mount moments later; a ServiceAccount, Role and RoleBinding a migration Job needs are commonly annotated with the same event so they exist before the Job that uses them. ### Reading a hook's output Because a hook runs inside the cluster, its output does not naturally reach the terminal you typed `helm upgrade` into. The annotation `helm.sh/hook-output-log-policy` fixes that: give it `hook-succeeded`, `hook-failed`, or both comma-separated, and Helm prints that hook Pod's logs to its own output on the matching condition, so you do not have to race to `kubectl logs`. ### Where people go wrong The two classic errors are assuming a hook is just "a Job Helm runs" — it is a phase, and Helm stops the world for it — and assuming a hook's resources are part of the release. Anything that must converge with the chart, be pruned when removed and be restored on rollback belongs in the release manifest as an ordinary template, not behind a hook annotation.