Skip to content
Tutorials Center
My learning

Topics

Lesson 7 of 38 ยท Charts and Releases

Install, Upgrade and Rollback

Master the Helm release loop: install a chart, change it with helm upgrade, inspect the revision history, compare revisions and roll back safely.

The daily life of a Helm user is a loop of three commands: install a release once, upgrade it many times, and roll back when something goes wrong. This lesson explains what each command does to the cluster and to Helm's own records, with the exact semantics that surprise newcomers.

Install

Terminal
helm install blog ./webapp -n prod --create-namespace -f values-prod.yaml

Install fails if a release of that name already exists in the namespace. Chart sources can be a repository chart (bitnami/nginx), a local directory, a .tgz archive, an OCI reference (oci://registry.example.com/charts/webapp) or a URL. You can pin a version with --version 1.2.3.

If any resource fails to create, Helm marks the release failed and leaves whatever was created in place unless you use --atomic (see Upgrade Flags). A failed first install still occupies the name, so you must helm uninstall it before trying again, or use helm upgrade --install.

Upgrade

Terminal
helm upgrade blog ./webapp -n prod -f values-prod.yaml --set image.tag=1.4.3

upgrade renders the chart again with the new inputs, compares the result with the previous revision's manifest and the live objects, and patches only what changed (a three-way merge). Resources that vanished from the new chart are deleted, new ones are created. Then a new revision is stored.

flowchart LR
  A["Old manifest (revision N)"] --> M{"Three-way merge"}
  B["New manifest (from chart + values)"] --> M
  L["Live objects in the cluster"] --> M
  M --> P["Patch sent to the API"]
  P --> R["Revision N+1 stored"]

Using the live state as the third input means manual edits to fields Helm manages can be reverted, and fields Helm never set are left alone.

An important rule about values

By default helm upgrade does not remember the values from earlier installs. It starts again from the chart's defaults plus whatever you pass this time. So this sequence surprises people:

Terminal
helm install blog ./webapp --set replicaCount=5
helm upgrade blog ./webapp --set image.tag=1.4.3
# replicaCount is back to the default, not 5!

Safe habits:

  1. Keep all your overrides in files under version control and pass them every time (-f values-prod.yaml). This is the recommended approach.
  2. Or use --reuse-values (reuse last release's values) or --reset-then-reuse-values; the trade-offs are in the next lesson.

History and comparing revisions

Terminal
helm history blog -n prod
TEXT
REVISION  UPDATED                   STATUS      CHART         APP VERSION  DESCRIPTION
1         Mon Mar 10 09:00:00 2025  superseded  webapp-0.3.0  2.7.0        Install complete
2         Mon Mar 10 11:30:00 2025  superseded  webapp-0.3.1  2.8.0        Upgrade complete
3         Tue Mar 11 08:12:00 2025  deployed    webapp-0.3.1  2.8.0        Upgrade complete

Exactly one revision is deployed; the rest are superseded or failed. Inspect any of them:

Terminal
helm get values blog -n prod --revision 2
helm get manifest blog -n prod --revision 2

To see what an upgrade would change, install the community helm-diff plugin: helm diff upgrade blog ./webapp -f values-prod.yaml prints a colored diff, which is the single best safety net for reviewing changes. The stand-in below compares two rendered manifests the same way, using Python's difflib.

Python Stand-in: diff two revisions

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.

Rollback

Terminal
helm rollback blog 2 -n prod

Rollback applies the manifest and values of revision 2 and records them as a new revision. Leaving out the number rolls back to the previous revision. After the command above, helm history shows a revision 4 with the description Rollback to 2. Useful flags: --wait waits until resources are ready, --cleanup-on-fail deletes resources created during a failed rollback, and --dry-run previews.

Rollback restores Kubernetes objects. It cannot undo effects outside the manifests: a database migration run by a hook, data written by the app, or a deleted PersistentVolume stays as it is. Plan migrations to be backward compatible so a rollback stays safe.

Python Stand-in: upgrade, fail, rollback

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.

A rollback with no number goes to the revision just before the latest one. Here the latest is the failed revision 3, so the release returns to revision 2 and the result is recorded as revision 4.

Upgrade or install in one command

For scripts and CI, make the command idempotent:

Terminal
helm upgrade --install blog ./webapp -n prod --create-namespace -f values-prod.yaml

If blog exists it is upgraded, otherwise installed. This is the form you will see in nearly every pipeline. Combine it with --atomic --timeout 5m to roll back automatically on failure.

Limiting history

Every revision is a Secret of up to a megabyte. Helm keeps the last 10 by default; set --history-max 5 on upgrade (or 0 for unlimited) so old Secrets are pruned and kubectl get secrets stays tidy.

Do not edit Helm-managed objects with kubectl edit or kubectl scale as a routine fix. The change is invisible to Helm, may be overwritten by the next upgrade and makes helm get manifest lie about reality. Change a value and upgrade instead.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. You run helm upgrade without -f or --set, after installing with --set replicaCount=5. What happens to replicaCount?

    Without --reuse-values, upgrade starts from the chart defaults plus the values you pass now.
  2. 2. After helm rollback blog 2 from revision 3, which revision is current?

    Rollback creates a new revision; history is append-only.
  3. 3. Which command is idempotent for pipelines?

    It installs when the release is missing and upgrades otherwise.
  4. 4. What can rollback NOT undo?

    Rollback only restores Kubernetes objects from the stored manifest.
  5. 5. What does --history-max control?

    Older revision Secrets beyond the limit are deleted.

Summary

  • helm install creates revision 1; helm upgrade renders again and patches the difference as a new revision.
  • Upgrades forget old --set values unless you keep overrides in files or use --reuse-values.
  • helm history, get values --revision and the helm diff plugin show what changed.
  • Rollback creates a new revision copying an old one and cannot undo data or migrations.
  • Use helm upgrade --install in scripts and --history-max to limit stored revisions.

Next: Release Lifecycle Commands