skip to content

What does Helm's --timeout flag bound on install and upgrade, and what is its default?

level: juniorimportance: should knowfreq 55%

answer

  1. Only bites while Helm is waiting
  2. A budget, not a stopwatch on the command
  3. Written as a duration, not seconds
  4. Five minutes unless you say otherwise
  5. Expiry marks failed, removes nothing

basics

~20 s

--timeout is the budget for the waiting Helm does during a release: hook execution and, when a wait strategy is on, readiness. It takes a Go duration string such as 9m30s and defaults to 5m0s.

solid answer

~40 s

`--timeout` is a **duration**, not a number of seconds: you write `30s`, `9m30s` or `1h`, and it defaults to `5m0s`. It bounds an individual Kubernetes operation Helm is waiting on, not the wall-clock life of the command, so it is only interesting when Helm is actually waiting for something - hook resources always, and rendered workloads only when a wait strategy is switched on. When the budget expires Helm stops watching, exits non-zero with a timeout error, and records the revision as failed. The objects it already applied stay in the cluster and Kubernetes carries on reconciling them, so an app can become perfectly healthy a minute after Helm gave up on it. Whether anything gets undone is the business of a separate flag, not of `--timeout`.

code

bash · 7 lines
bash
CHART=oci://registry.internal/charts/invoice-worker

# Default budget: 5m0s, which a 7m14s rollout will blow through
helm upgrade --install invoice-worker "$CHART" --version 2.14.3 -n billing --wait

# Budget sized from the measured rollout instead
helm upgrade --install invoice-worker "$CHART" --version 2.14.3 -n billing --wait --timeout 12m

go deeper

for a junior

Be ready to state the default (5m0s) and to write the value as a duration such as 9m30s rather than a bare number. Knowing that it governs waiting, and that a timeout does not delete anything, is enough at this level.

for a middle

Explain why the flag looks inert on a chart with no hooks and no wait strategy, and what exactly changes when a wait is switched on. Be able to describe the three effects of expiry: non-zero exit, a failed revision record, and untouched cluster objects.

for a senior

Show that you size the budget from measured rollout time rather than copying a number, and that you keep the surrounding CI step's limit above Helm's. Be ready to say why a very large timeout is a symptom rather than a fix.

for a principal

Own the policy question: whether one timeout is set fleet-wide or per chart, what a timed-out release means for the team on call, and how you stop pipelines from silently absorbing timeouts as normal. Argue the tradeoff between fast failure and false alarms.

## What the flag is `--timeout` appears on `helm install`, `helm upgrade`, `helm rollback` and `helm test`. Its value is a **Go duration string**: an integer with a unit, optionally several of them - `45s`, `12m`, `9m30s`, `1h30m`. It is not a plain count of seconds; a bare number has no unit and is not a valid duration. Its default is `5m0s`, which is where the familiar "300 seconds" figure comes from. ## What it actually bounds The mental model people arrive with is a stopwatch on the whole command: "kill `helm upgrade` if it has not finished in five minutes". That is not what the flag does. `--timeout` is the budget for the individual Kubernetes operations Helm blocks on while it drives the release - most visibly, the time it will keep watching resources before concluding they are never going to get where they were asked to go. That has one large consequence: **`--timeout` only matters when Helm is waiting at all.** In Helm 4 the default wait strategy is `hookOnly`, so an upgrade with no `--wait` at all returns as soon as the API server has accepted the manifests, and the only thing the timeout ever governed was hook execution. Add a wait strategy and the same 5m0s suddenly becomes the deadline your rollout has to beat. Teams routinely discover `--timeout` on the day they first add `--wait`, because that is the day it starts failing builds. The other parts of the command are not what the budget is about. Resolving and pulling the chart, rendering templates, and computing the diff are not the operation the flag is protecting you from; the flag exists because *cluster* operations can hang indefinitely and a CLI that hangs indefinitely is useless in a pipeline. ## What happens when it expires Three things, and candidates usually only name the first: 1. Helm stops watching and returns a non-zero exit code with an error naming the timeout. 2. The release revision is recorded with status `failed`, which is what `helm status` and `helm history` will report from then on. 3. **Nothing is removed.** Every object Helm already applied is still in the cluster, and the controllers responsible for them keep working. A Deployment that was three pods short when the budget ran out may be fully available thirty seconds later, while Helm's stored record insists the release failed. Reconciling that gap - deciding whether to retry, roll back or simply re-check - is a human decision, or a separate flag's job; `--timeout` itself has no opinion about undoing anything. ## Choosing a value Measure, do not guess. Take a concrete case: an invoice-rendering worker chart published to an OCI registry by CI. Its upgrade pulls a 1.4 GB image onto six nodes and its pods spend a while warming a template cache, so a healthy rollout reaches ready at about **7m14s**. Against the default 5m0s, *every* successful deploy is reported as a failure. The fix is not to remove `--wait`, it is to give the wait a budget that reflects the workload: something like `--timeout 12m`, comfortably above the observed p95 but still low enough that a genuinely stuck rollout is caught in one coffee break rather than one afternoon. Two practical corollaries. First, the surrounding job needs a longer limit than Helm does - a CI step killed at ten minutes makes a twelve-minute Helm timeout meaningless, and you lose Helm's diagnostic error along with it. Second, a very large timeout is a smell: an hour-long budget usually means somebody is papering over a workload whose readiness signal never settles, and the pipeline has quietly stopped telling anyone about it. ## Common misreadings - "It defaults to no limit." It defaults to `5m0s`. - "It caps the whole command." It bounds the operations Helm waits on. - "It rolls things back." It does not; it stops waiting and marks the revision failed. - "It applies even without waiting." Only hook execution is bounded when no wait strategy is on, so on a chart with no hooks the flag can look inert.

  • Does --timeout limit how long the whole helm upgrade command may run?
    No. It bounds the individual Kubernetes operations Helm blocks on - hook execution and readiness watching - rather than acting as a wall-clock limit on the process. Chart resolution, rendering and the API calls themselves are not what the budget is protecting; it exists because cluster-side waiting can hang forever. If you want a hard ceiling on the command, put one on the surrounding CI step, and make it comfortably larger than Helm's own timeout so Helm's error still reaches you.
  • The timeout expired during an upgrade. What state is the release and the cluster in?
    The command exits non-zero and the revision is stored with status failed, so helm status and helm history report a failed release. The cluster is untouched by the expiry itself: everything Helm applied is still there and its controllers keep reconciling, so the workload may reach a healthy state moments later while Helm's record still says failed. Deciding what to do about that mismatch is separate from the timeout.
  • Why do teams often not notice --timeout until they add a wait strategy?
    Because with no wait strategy Helm only ever waits on hook resources, and a chart with no hooks gives the timeout nothing to bound - the command returns as soon as the API server accepts the manifests. The moment a wait strategy is switched on, the same default 5m0s becomes the deadline the rollout has to beat, and any workload slower than that starts failing pipelines that used to pass.

It is a parking meter on the waiting, not a stopwatch on the errand: when it runs out Helm walks away, but everything it already put in the cluster stays exactly where it is.

saying these in an interview costs you the question

  • Says --timeout has no default and waits forever
  • Treats it as a wall-clock cap on the whole command
  • Expects expiry to delete or revert applied resources
  • Passes a plain number expecting seconds
  • Thinks the timeout cancels the Kubernetes rollout too
  • Sets an hour-long timeout instead of fixing readiness

context

resolving links…