Releases, hooks and debugging¶
Status: AI draft, 2026-11-16. Not yet verified by me. Written from the Helm 4 documentation; the Helm commands were not run for this page, so they have no sample output.
In one line¶
Every helm install or upgrade creates a numbered revision of a release, stored by default as a Secret in the release's namespace; helm rollback re-applies an earlier revision. Hooks run Jobs or other resources at set points (before or after install, upgrade, delete), and helm template, --dry-run, helm get manifest and helm history are the main debugging tools.
The plain idea¶
kubectl apply forgets: it does not know which objects belonged to last week's version of your app. Helm remembers. A release is one installation of a chart under a name (sample-app in namespace team-a), and each change creates a new revision recording the chart, the values and the rendered manifest. That record is what lets Helm upgrade cleanly (delete what the new version no longer has), show history, and roll back.
Some steps do not fit "apply these objects": run a database migration before the new version starts, or a smoke test after. Hooks are templates marked to run at those points.
How it works¶
Releases and revisions¶
flowchart TD
I["helm install: revision 1,<br/>status deployed"] --> U["helm upgrade: revision 2 deployed,<br/>revision 1 superseded"]
U --> F["helm upgrade fails: revision 3 failed"]
F --> R["helm rollback sample-app 2:<br/>revision 4, same content as 2"]
- Where state lives: by default in Secrets in the release's namespace, one per revision (named like
sh.helm.release.v1.sample-app.v2). TheHELM_DRIVERenvironment variable can switch to ConfigMaps or SQL. - History:
--history-maxkeeps 10 revisions by default on upgrade; older ones are pruned. - Status values include
deployed,superseded,failed,pending-install,pending-upgrade,pending-rollbackanduninstalled. - Rollback is a new revision with an old revision's content, not a time machine: data changes made by migrations stay changed.
Install and upgrade flags that matter (Helm 4)¶
| Flag | Meaning |
|---|---|
upgrade --install |
Install if the release does not exist, else upgrade: one command for CI |
--wait |
Wait until resources are ready, up to --timeout; strategies watcher (the default when given alone), hookOnly, legacy |
--timeout |
Per-operation limit, default 5 minutes |
--rollback-on-failure |
On failure, roll back to the last successful revision (Helm 3 called this --atomic); implies --wait |
--cleanup-on-fail |
Delete resources this failed upgrade created |
--server-side |
true, false or auto: use server-side apply (kubectl fluency) |
--force-replace |
Delete and recreate resources that cannot be updated in place (Helm 3 called this --force); causes downtime |
--create-namespace |
Create the release namespace if missing |
--reset-values, --reuse-values, --reset-then-reuse-values |
How values from the previous revision are treated on upgrade |
Hooks¶
A hook is any template with the annotation helm.sh/hook:
| Hook | Runs |
|---|---|
pre-install, post-install |
Before any resources are created, or after all are loaded |
pre-upgrade, post-upgrade |
Around an upgrade |
pre-delete, post-delete |
Around uninstall |
pre-rollback, post-rollback |
Around rollback |
test |
When helm test is run |
apiVersion: batch/v1
kind: Job
metadata:
name: {{ .Release.Name }}-migrate
annotations:
"helm.sh/hook": pre-upgrade,pre-install
"helm.sh/hook-weight": "-5"
"helm.sh/hook-delete-policy": before-hook-creation,hook-succeeded
spec:
backoffLimit: 1
template:
spec:
restartPolicy: Never
containers:
- name: migrate
image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
command: ["./migrate", "up"]
- Weights (strings, may be negative) order hooks of the same type; lower runs first. Helm waits for each hook (Jobs until they complete) before moving on, so a failing migration fails the upgrade before the new pods start.
- Delete policies:
before-hook-creation(the default: delete the old one before creating the new),hook-succeeded,hook-failed. - Hook resources are not part of the release:
helm uninstalldoes not delete them, so set a delete policy or a Job TTL (Jobs and CronJobs). - GitOps tools map Helm hooks to their own sync phases (Sync, hooks and waves).
Dependencies and OCI charts¶
dependenciesinChart.yamllists subcharts with versions and repositories;helm dependency updatedownloads them intocharts/. Aconditionsuch aspostgresql.enabledswitches one on or off.- Charts can be stored in OCI registries such as ECR (ECR):
helm packagethenhelm push sample-app-1.4.2.tgz oci://<registry>/charts, and install withhelm install sample-app oci://<registry>/charts/sample-app --version 1.4.2.
Debugging¶
| Question | Command |
|---|---|
| What would this render to? | helm template sample-app ./chart -f values-prod.yaml |
| Would the cluster accept it? | helm upgrade --install ... --dry-run=server |
| What is deployed right now? | helm get manifest sample-app -n team-a |
| With which values? | helm get values sample-app -n team-a (add --all for computed values) |
| What happened over time? | helm history sample-app -n team-a |
| What changed between revisions? | Diff helm get manifest --revision N against --revision M |
| What do the hooks look like? | helm get hooks sample-app -n team-a |
A concrete example¶
CI deploys sample-app on every merge:
helm upgrade --install sample-app oci://<registry>/charts/sample-app --version 1.4.2 \
-n team-a --create-namespace \
-f values-prod.yaml --set image.tag=1.4.2 \
--rollback-on-failure --timeout 10m
- The
pre-upgrademigration Job runs first; if it fails, the upgrade fails and nothing else changes. - Then the Deployment rolls out (Deployments and rollouts); Helm waits until it is ready.
- If readiness does not arrive within 10 minutes, Helm rolls back to the last good revision and the pipeline fails, with
helm historyshowing both revisions. - The migration is not undone by the rollback, so migrations must be backwards compatible with the previous version (expand first, contract later).
Why not just...?¶
- ...
kubectl applythe output ofhelm template? That works, and GitOps tools often do the equivalent, but you lose Helm's release history, rollback, pruning of removed objects and hooks, unless the GitOps tool provides its own. - ...rely on
helm rollbackto undo a bad release? It reverts manifests, not data or external side effects. Database migrations, messages sent and files written stay. Design changes to be backward compatible. - ...use
--force-replacewhen an upgrade fails on an immutable field? It deletes and recreates the object, causing downtime, and for some objects (a Service's ClusterIP, a StatefulSet) changes identity. Understand which field is immutable first.
Commands to know¶
These were not run for this page.
| Command | What it does |
|---|---|
helm list -n team-a (or -A) |
Releases, revision, status, chart and app version. |
helm status sample-app -n team-a |
Current status and notes. |
helm history sample-app -n team-a |
Every revision with status and description. |
helm rollback sample-app 2 -n team-a |
Re-apply revision 2 as a new revision. |
helm uninstall sample-app -n team-a |
Delete the release's resources (not hook resources, not PVCs created by StatefulSets). |
helm test sample-app -n team-a |
Run the chart's test hooks. |
kubectl get secrets -n team-a -l owner=helm |
The stored revisions. |
How it breaks¶
| Symptom | Layer | Check | Likely cause |
|---|---|---|---|
another operation (install/upgrade/rollback) is in progress |
Release state | helm history: last status pending-upgrade |
A previous run was killed mid-way; roll back to the last deployed revision |
field is immutable on upgrade |
Kubernetes | Which field | Changed a Deployment selector, a Job template, a StatefulSet's volume claims |
rendered manifests contain a resource that already exists |
Ownership | Object annotations | Object created outside Helm or by another release |
| Upgrade timed out, pods look fine | Waiting | Hook Jobs, --timeout |
A hook Job still running or failing, or readiness slower than the timeout |
| Old hook Job blocks the next upgrade | Hook cleanup | Delete policy | No before-hook-creation policy and the Job still exists |
| Uninstall left resources behind | Ownership | What remains | Hook resources, helm.sh/resource-policy: keep, PVCs from StatefulSets |
Interview questions¶
1. What is a Helm release, and where is its state stored?
Answer
- One installation of a chart under a name in a namespace, with numbered revisions.
- Each revision stores the chart, values and rendered manifest.
- By default in Secrets in the release's namespace; ConfigMap or SQL backends are options.
2. How does helm rollback work, and what does it not undo?
Answer
- It re-applies an earlier revision's manifest as a new revision.
- It does not undo data changes, migrations, external side effects or hook results.
- So changes must be backward compatible.
3. A deploy fails with "another operation is in progress". What happened and how do you fix it?
Answer
- A previous Helm run stopped mid-way and left the release
pending-upgrade(or install or rollback). helm historyshows it;helm rollbackto the last deployed revision clears it.- Prevent it with timeouts and
--rollback-on-failure, and by not cancelling CI jobs mid-deploy.
4. How would you run a database migration with Helm?
Answer
- A Job with
helm.sh/hook: pre-upgrade,pre-install, a weight, and a delete policy. - Helm waits for it; failure stops the upgrade before new pods start.
- Make migrations backward compatible, because rollback will not undo them.
5. What does --rollback-on-failure do (formerly --atomic)?
Answer
- Waits for the release to become ready and, on failure or timeout, rolls back to the last successful revision.
- Keeps the cluster on a working version after a failed CI deploy.
- Helm 4 renamed the flag; Helm 3 used
--atomic.
6. How do you see exactly what is deployed and with which values?
Answer
helm get manifestandhelm get values(with--allfor merged values), optionally--revision N.helm historyfor the sequence of changes.- Compare with
helm templateof the new version before upgrading.
Try it¶
If you have Helm and a kind cluster (Helm is not part of these notes' toolchain):
- Install a chart from
helm createtwice with differentreplicaCountvalues; runhelm history, thenkubectl get secrets -l owner=helm. - Roll back to revision 1 and predict the revision number of the result.
- Add a
pre-upgradeJob that runsexit 1, upgrade, and readhelm historyandhelm status.
Without Helm: write the hook annotations for a smoke test that runs after every install and upgrade and is deleted when it succeeds.
Zoom out¶
Releases, hooks and rollback are what Helm adds beyond templating (Charts, templates and values). In GitOps setups the GitOps controller takes over release tracking and sync order, and Helm becomes a renderer (Sync, hooks and waves, Promotion and rollback).