Skip to content
Tutorials Center
My learning

Topics

Lesson 9 of 38 ยท Charts and Releases

Upgrade Flags and Safe Deployments: --atomic, --wait and --reuse-values

Deploy safely with Helm: --wait, --timeout, --atomic, --cleanup-on-fail, --dry-run, --force and the differences between reuse-values and reset-then-reuse-values.

helm install and helm upgrade accept dozens of flags. A handful decide whether a deployment is merely sent or actually verified, and whether a failure leaves a mess behind. This lesson explains the flags you will use in every pipeline and the value-merging modes that cause the most surprises.

By default Helm does not wait

Without extra flags Helm returns as soon as the Kubernetes API has accepted the objects. The Deployment may still be rolling out, pods may crash, and the command reports success. That is rarely what a pipeline wants.

Terminal
helm upgrade --install blog ./webapp -n prod --wait --timeout 5m

--wait makes Helm block until the resources are ready: Deployments, StatefulSets and DaemonSets have their desired pods Ready, Services of type LoadBalancer have an address, Jobs are not waited for unless you add --wait-for-jobs. If readiness is not reached within --timeout (default 5 minutes), Helm gives up and marks the revision failed. The check relies on your readiness probes (Probes): without them a pod counts as ready the moment its container starts.

--atomic: undo on failure

Terminal
helm upgrade --install blog ./webapp -n prod --atomic --timeout 5m

--atomic implies --wait and adds an automatic cleanup. On a failed install the release is uninstalled; on a failed upgrade Helm rolls back to the previous revision. Either way the cluster ends in the state it was before your command. This is the closest Helm gets to a transactional deploy and is the recommended default for CI.

Related flags:

Flag Effect
--wait Block until resources are ready
--wait-for-jobs Also wait for Jobs to complete
--timeout 10m Maximum time for the operation (also covers hooks)
--atomic Roll back or uninstall automatically on failure
--cleanup-on-fail Delete resources created in this failed run (without rolling back older ones)
--dry-run Render and validate without applying (--dry-run=server also asks the API server)
--debug Verbose output
--description "msg" Text stored in helm history
--history-max N Revisions to keep
--create-namespace Create the namespace if absent
--force Delete and recreate objects when a patch fails (disruptive; avoid)
--no-hooks Skip hooks
--skip-crds Do not install CRDs from crds/

--dry-run=server is stronger than the plain client-side check: the API server validates the objects against its schema and admission rules, catching mistakes such as a wrong field type that rendering alone cannot see.

What --atomic does, step by step

flowchart TB
  S["helm upgrade --atomic --timeout 5m"] --> A["Apply new manifests (revision N+1)"]
  A --> W{"Ready within timeout?"}
  W -- yes --> OK["Mark N+1 deployed"]
  W -- no --> F["Mark N+1 failed"]
  F --> RB["Automatic rollback: new revision N+2 = copy of N"]

A failed atomic upgrade leaves two extra history lines: the failed revision and the rollback.

The program below models a deployment whose new pods never become ready, with and without --atomic.

Python Stand-in: atomic versus non-atomic upgrade

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Without --atomic the broken image stays live (Kubernetes may keep the old pods running during a rolling update, but the desired state is the broken one). With it, the release returns to the last good image.

How values are carried between upgrades

As covered in Install, Upgrade and Rollback, upgrade does not remember earlier overrides. Three flags decide what happens to them:

Mode Behavior
default Chart defaults (of the new chart) + values you pass now. Earlier --set values are dropped.
--reuse-values The previous release's computed values (old chart defaults included) + values you pass now. New defaults added by a newer chart are not picked up.
--reset-then-reuse-values New chart defaults + previous release's user overrides + values you pass now. Usually what people expect.
--reset-values Explicitly use only the new chart defaults + values you pass now.

The trap with --reuse-values is subtle: if chart 0.4.0 adds a new key metrics.enabled: true, a release upgraded with --reuse-values keeps the old computed values that lack that key, so templates behave as if the key were unset or missing, and may fail on a nil value. The stand-in makes the difference concrete.

Python Stand-in: reuse-values merging modes

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Look at each line: only --reset-then-reuse-values has both the old replicas: 5 and the new metrics key. --reuse-values is missing metrics; the default mode lost replicas: 5.

The most robust answer is to avoid the whole question: store every override in a values file in Git and always pass it. Then each upgrade is fully described by the chart version and the files, which also makes it reproducible.

--set flags versus values files in pipelines

Terminal
helm upgrade --install blog ./webapp -n prod \
  -f values/base.yaml -f values/prod.yaml \
  --set image.tag="$GIT_SHA" \
  --atomic --timeout 5m --history-max 10

Later -f files override earlier ones, and --set overrides all files. Reserve --set for the few values computed at deploy time, such as the image tag; everything else belongs in a reviewed file.

If a deployment hangs for the whole timeout, run kubectl get pods -n prod and kubectl describe pod in another terminal while Helm waits. The usual causes are an image that cannot be pulled, a failing readiness probe, or insufficient cluster resources (see Debugging Apps in the Cluster).

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does --atomic imply?

    --atomic waits for readiness and cleans up when the operation fails.
  2. 2. A newer chart adds a default value. Which upgrade mode would NOT receive it?

    --reuse-values reuses the old computed values, which lack the new key.
  3. 3. Which flag validates the manifests against the API server without applying them?

    Server-side dry run runs schema validation and admission without persisting.
  4. 4. Why does --wait depend on readiness probes?

    Helm uses pod readiness, which comes from probes; a missing probe means ready immediately.

Summary

  • Use --wait (or --atomic) with a --timeout so a deployment is verified, not just sent.
  • --atomic rolls back a failed upgrade or uninstalls a failed install automatically.
  • --dry-run=server catches schema and admission errors before changing anything.
  • Prefer keeping all overrides in files under version control; if not, understand --reuse-values versus --reset-then-reuse-values.
  • --set is for values computed at deploy time, such as the image tag.

Next: Go Templates: The Basics