Skip to content
Tutorials Center
My learning

Topics

Lesson 8 of 38 ยท Charts and Releases

Release Lifecycle Commands: list, status, get, history and uninstall

Inspect and manage Helm releases: helm list filters, status, the get subcommands, history, uninstall with keep-history, and how release Secrets are encoded.

Once releases exist in a cluster, you need to find them, inspect them and eventually remove them. Helm has a compact set of commands for the whole lifecycle. This lesson covers each one with its useful options, then looks inside the Secret that backs a release, which makes debugging much easier.

helm list

Terminal
helm list                       # releases in the current namespace
helm list -A                    # all namespaces (--all-namespaces)
helm list -n prod --filter 'blog'  # regex on the name
helm list --failed --pending    # by status
helm list -o json | jq '.[].name'
TEXT
NAME   NAMESPACE  REVISION  UPDATED                   STATUS    CHART         APP VERSION
blog   prod       3         2025-03-11 08:12:00 +0000 deployed  webapp-0.3.1  2.8.0
docs   prod       1         2025-03-10 09:00:00 +0000 deployed  webapp-0.3.1  2.8.0

By default only deployed and failed releases show. Add --all to include uninstalled releases kept with --keep-history. Output formats are table, json and yaml, handy for scripts. Release statuses you will meet:

Status Meaning
deployed The current, live revision
superseded An older revision replaced by a newer one
failed An install or upgrade that did not finish
uninstalled Removed but history was kept
pending-install, pending-upgrade, pending-rollback An operation is in progress (or was interrupted)
uninstalling Removal in progress

A release stuck in pending-* usually means a previous Helm process was killed; see the troubleshooting tips at the end.

helm status

Terminal
helm status blog -n prod
helm status blog -n prod --show-resources

It prints the release metadata and the chart's rendered notes. --show-resources adds a table of the Kubernetes objects and their state, a quick sanity check that the pods are up.

helm get: look at what is deployed

helm get has subcommands that read from the stored release record:

Command Output
helm get values blog Values you supplied (user overrides only)
helm get values blog --all Overrides merged with chart defaults (computed values)
helm get manifest blog The rendered YAML that was applied
helm get notes blog The rendered NOTES.txt
helm get hooks blog Hook manifests (see the Dependencies and Hooks chapter)
helm get metadata blog Chart name, version, app version, namespace, revision, status
helm get all blog Everything above

Every one accepts --revision N to look at an older revision. A good debugging routine when an environment misbehaves is: helm get values (what did we ask for?), then helm get manifest (what did Helm send?), then kubectl get (what is actually running?).

helm history

Terminal
helm history blog -n prod --max 5

Prints the revision table you saw in the previous lesson, newest last. -o json is available too.

helm uninstall

Terminal
helm uninstall blog -n prod
helm uninstall blog -n prod --keep-history
helm uninstall blog -n prod --wait --timeout 5m

Uninstall deletes every object recorded in the release's manifest and then removes the release Secrets. With --keep-history the secrets stay and the release shows as uninstalled, which allows helm rollback to bring it back:

Terminal
helm list --uninstalled
helm rollback blog 3 -n prod      # resurrects an uninstalled release

Resources that carry the annotation helm.sh/resource-policy: keep are left behind on purpose. Charts use it for things whose deletion would lose data, such as a PersistentVolumeClaim or a Secret with generated credentials.

YAML
metadata:
  annotations:
    "helm.sh/resource-policy": keep

helm uninstall is destructive: it deletes Deployments, Services and anything else in the release without a confirmation prompt. Always check kubectl config current-context and the -n flag first.

Inside a release Secret

Helm stores revision N of release blog as a Secret named sh.helm.release.v1.blog.vN with the labels owner=helm, name=blog, status=deployed and version=N. Its data.release field is the release serialized as JSON, compressed with gzip and base64 encoded. Because Kubernetes base64 encodes Secret data once more, you decode twice:

Terminal
kubectl get secret sh.helm.release.v1.blog.v3 -n prod -o jsonpath='{.data.release}' \
  | base64 -d | base64 -d | gunzip | jq '{name, version, info: .info.status, chart: .chart.metadata.version}'

The next program reproduces the encoding, so you can see why two base64 -d calls are needed and what the JSON contains.

Python Stand-in: encode and decode a release record

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.

Real releases carry the whole chart and manifest, so a Secret can reach hundreds of kilobytes. Kubernetes limits an object to about 1 MB (etcd's limit), and a very large chart can make helm install fail with Secret ... is invalid: data: Too long. The fix is to shrink the chart or the manifest, for example by moving large static files out of it.

Pruning old revisions

Helm keeps only a limited number of revisions per release. The --history-max flag on upgrade controls it (default 10). The stand-in shows the policy: after each upgrade, the oldest revisions beyond the limit are deleted, but the current one is always kept.

Python Stand-in: history-max pruning

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.

Troubleshooting stuck releases

  • another operation (install/upgrade/rollback) is in progress: a previous run was interrupted and left the release in a pending-* state. Check helm history. If no Helm process is running, roll back to the last good revision (helm rollback blog N) or, for a failed first install, helm uninstall blog.
  • has no deployed releases: the first install failed and nothing is deployed. Uninstall it and install again, or use helm upgrade --install after cleaning up.
  • Resource already exists / not owned by Helm: an object with that name exists but lacks Helm's ownership labels and annotations. Delete it or adopt it by adding app.kubernetes.io/managed-by=Helm plus meta.helm.sh/release-name and meta.helm.sh/release-namespace annotations, then retry.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which command shows the user-supplied values merged with chart defaults?

    --all returns the computed values, including defaults.
  2. 2. What does helm uninstall --keep-history do?

    The release stays listed as uninstalled and can be resurrected with helm rollback.
  3. 3. How is the data of a release Secret encoded?

    Helm stores base64(gzip(json)); the Secret API base64 encodes the data field again.
  4. 4. Which annotation makes uninstall leave a resource in place?

    The resource-policy keep annotation tells Helm not to delete the object.

Summary

  • helm list, status, get and history answer what is deployed, with --revision to look back.
  • helm get values --all shows the computed values; get manifest shows the YAML applied.
  • helm uninstall deletes the release's objects; --keep-history allows a later rollback and helm.sh/resource-policy: keep protects individual resources.
  • Releases live in Secrets sh.helm.release.v1.NAME.vN holding double-base64 gzip JSON, pruned by --history-max.

Next: Upgrade Flags and Safe Deployments