Tell customers to use the wait behavior with a sensible timeout and to turn on rollback on failure, so a bad upgrade returns to the last good release instead of hanging half applied. The Helm upgrade reference documents both, along with the default timeout of five minutes.
Definitions
Helm tracks each install or upgrade as a revision of a release. An upgrade applies a new chart version or new values. If it fails midway, the release can be left in a failed state unless you ask Helm to roll back.
The flags from the Helm reference
| Flag | What the reference says | Default |
|---|---|---|
| wait | Wait until resources are ready, up to the timeout. Bare use selects the watcher strategy | hookOnly when omitted |
| timeout | Time to wait for any individual Kubernetes operation, such as Jobs for hooks | 5m0s |
| rollback-on-failure | If set, Helm rolls the upgrade back to the previous successful release on failure. Setting it makes wait default to watcher | Not set |
| history-max | Maximum revisions saved per release, 0 for no limit | 10 |
| reuse-values | Reuse the last release values and merge overrides | Not set |
| reset-values | Reset values to those built into the chart | Not set |
The reference I read documents rollback-on-failure and does not list an atomic flag. Older guides use atomic, so test the exact Helm version you support and write your guide to match.
What to put in your upgrade guide
- A tested command line for the supported Helm version, with wait, a timeout sized to your slowest pod start, and rollback on failure.
- A note on database migrations: a chart rollback does not reverse a schema change. Say what is safe to roll back and for how long. See expand and contract migrations.
- A statement on values: whether customers should reuse the last values or reset to chart defaults when a chart adds new required values.
- How to check the result: the history command, then your health endpoint.
- How to open a support case with the release revision number.
Values: a frequent trap
Reuse values keeps the previous release's values and merges your overrides. Reset values returns to the chart defaults. After a security release that changes a default, reusing old values can keep an unsafe setting alive. State in your release note which one customers should use, and whether any value changed.
Timeout sizing
A timeout shorter than your slowest start will trigger a rollback of a healthy upgrade. Measure on a realistic dataset, then add margin.
If you want a second look at what you ship, Safeguard can generate and scan an SBOM and run dependency scanning with reachability analysis, and you can try the free scan.
Quick check
Does rollback on failure undo database changes?
No. It returns the Kubernetes resources to the previous release. Schema changes need their own plan.
Should customers reuse values or reset them?
Say so in each release note. If a security release changes a default, reusing old values can keep the old setting.
Sources
Last reviewed: 19 October 2026.
