Skip to main content
RunBook Academy

KubernetesCIV · HelmHelm

Helm releases and revisions — the lifecycle of an installed chart

Advanced⏱ ~17 minhelmkubectl

What you'll learn

  • Understand Helm releases and revisions
  • Use helm list, helm history, helm status, helm rollback
  • Reason about release state in Secrets and ConfigMaps
  • Apply the operational discipline of treating releases as production objects

Prerequisites

Verified against Kubernetes 1.34.x · kubeadm 1.34.x · kubectl 1.34.x · etcd 3.6.x · CoreDNS 1.11.x · containerd 1.7.x / 2.x · 2026-08-16

Not yet marked complete on this device.

A Helm release is an installed instance of a chart with a name, a namespace, and a history of revisions. This lesson walks releases and revisions, the release state, the helm commands, and the operational discipline.

Releases and revisions

flowchart LR
    A["Chart: mychart 1.0.0"] --> B["Release: myrelease"]
    A1["Chart: mychart 1.1.0"] --> B
    B --> R1[Revision 1]
    B --> R2[Revision 2]
    B --> R3[Revision 3]

The terminology:

  • Chart. The package (templates + values).
  • Release. An installed instance of a chart, identified by name in a namespace.
  • Revision. One version of a release. Every install, upgrade, or rollback creates a new revision.

A release named myrelease can have multiple revisions: revision 1 was the initial install, revision 2 was an upgrade, revision 3 was another upgrade.

The release state

flowchart LR
    A[helm install myrelease mychart] --> B["Secret: sh.helm.release.v1.myrelease.v1"]
    B --> C["Cluster: resources"]
    A1[helm upgrade myrelease mychart] --> B1["Secret: sh.helm.release.v1.myrelease.v2"]
    B1 --> C1["Cluster: updated resources"]

Helm stores the release state in Secrets in the release’s namespace. Each Secret contains:

  • The chart (with the values used for that revision).
  • The rendered manifest.
  • Metadata (revision number, status, timestamp).

The Secrets are named sh.helm.release.v1.<release- name>.v&lt;revision&gt;.

Helm commands

helm list -A
NAME            NAMESPACE   REVISION    UPDATED                                 STATUS      CHART           APP VERSION
myrelease       prod-app    3           2026-08-16 10:30:00.123456 +0000 UTC    deployed    mychart-1.1.0   2.0.0
argo-cd         argocd      5           2026-08-15 14:20:00.123456 +0000 UTC    deployed    argo-cd-5.0.0   2.6.0

The status is deployed for healthy releases, or failed, pending, or uninstalled for problems.

helm history myrelease -n prod-app
REVISION    UPDATED                                 STATUS      CHART           APP VERSION     DESCRIPTION
1           2026-08-10 09:00:00 +0000 UTC           superseded  mychart-1.0.0   1.0.0           Install complete
2           2026-08-12 14:30:00 +0000 UTC           superseded  mychart-1.1.0   1.5.0           Upgrade complete
3           2026-08-16 10:30:00 +0000 UTC           deployed    mychart-1.1.0   2.0.0           Upgrade complete

The history shows all revisions; the deployed revision is current; older revisions are superseded.

helm status myrelease -n prod-app
NAME: myrelease
LAST DEPLOYED: 2026-08-16 10:30:00 +0000 UTC
NAMESPACE: prod-app
STATUS: deployed
REVISION: 3
TEST SUITE: None
NOTES:
Thank you for installing mychart.

The status shows the current state, revision, and post-install notes.

helm rollback

helm rollback myrelease 2 -n prod-app

This rolls back myrelease to revision 2. Helm:

  1. Reads the Secret for revision 2.
  2. Renders the manifests from revision 2’s chart and values.
  3. Applies the manifests (creating a new revision with the rolled-back state).

The rollback is a new revision; the original revisions are preserved.

helm rollback myrelease 2 --wait --cleanup-on-fail -n prod-app

The --wait flag waits for resources to be ready; --cleanup-on-fail cleans up on failure.

The operational trade-offs

flowchart LR
    A[Helm releases] --> B[State in Secrets]
    A --> C[Rollback capability]
    A --> D[Chart dependencies]
    A --> E[Multi-cluster complexity]

The trade-offs:

  • State in Secrets. Release state is in Secrets; must be backed up.
  • Rollback capability. Helm can roll back to any previous revision — but only revisions still in history.
  • Chart dependencies. Dependencies (subcharts) are stored in charts/; updates may break the release.
  • Multi-cluster complexity. Each cluster has its own release state; syncing releases across clusters is manual.

Quiz

Knowledge check · 4 questions

  1. Q1. Where does Helm 3 store the state of a release?

  2. Q2. Helm release history is stored on the machine that ran `helm install`.

  3. Q3. Recover a release to a known-good configuration when the revision you want to roll back to has aged out of the history.

    `payments` in `prod-app` is on revision 12 and misbehaving; the last configuration anyone trusts is revision 6. `helm history payments -n prod-app` lists only revisions 8 to 12, and `helm rollback payments 6 -n prod-app` fails with `release: not found`. `kubectl -n prod-app get secret -l owner=helm,name=payments` returns five Secrets, `sh.helm.release.v1.payments.v8` through `v12`.

  4. Q4. What object does Helm 3 create for each revision of a release, what is it named, and how do you list them for one release?

Passing score: 75%. Answers are checked in this browser.

The operational discipline

Helm releases in production rest on five non-negotiable elements:

  • Pin chart and app versions. Never use latest or * in production.
  • Back up release state. The Secrets must be in the backup program.
  • Retain enough history. --history-max 10 or higher; without history, rollback is impossible.
  • Test upgrades in staging. A chart upgrade that breaks in production is a hot rollback.
  • Document the releases. The runbook lists the releases, their versions, and their purpose.

Helm releases are production objects. Treat them with the same rigour as any other Kubernetes resource.