Helm basics: install a chart, override values, upgrade and roll back

Helm is a package manager for Kubernetes. A chart is a package of templated manifests plus default settings (values.yaml). Installing a chart creates a release, a named instance in a namespace. Every install, upgrade or rollback gives the release a new revision number, starting at 1, and Helm keeps that history in the cluster.

The examples use the small public podinfo demo chart. Helm talks to whatever cluster your current kubeconfig context points at, so check it first with kubectl config current-context.

Step 1: find and inspect a chart

helm repo add podinfo https://stefanprodan.github.io/podinfo
helm repo update
helm search repo podinfo
helm show values podinfo/podinfo > default-values.yaml

helm search hub searches Artifact Hub instead of your added repositories. Many charts are also published as OCI images and can be installed directly from a oci:// URL without helm repo add.

Step 2: install a release

kubectl create namespace demo
helm install web podinfo/podinfo --namespace demo
helm list --namespace demo
helm status web --namespace demo

Step 3: customize with values

Never edit the chart. Put your overrides in your own file and keep it in Git:

replicaCount: 2
ui:
  message: "Hello from Helm"

helm upgrade web podinfo/podinfo --namespace demo -f my-values.yaml
helm get values web --namespace demo

• -f / --values can be given several times; the rightmost file wins.
• --set key=value overrides single values on the command line and has higher precedence than -f files. Nested keys use dots: --set ui.message=hi.
• Do not put real passwords in --set on shared machines; they end up in shell history, and Helm stores the supplied values in the release record.

Step 4: preview before you change anything

helm template web podinfo/podinfo -f my-values.yaml > rendered.yaml
helm upgrade web podinfo/podinfo --namespace demo -f my-values.yaml --dry-run=server

helm template renders the manifests locally so you can read or diff them. --dry-run simulates the operation without persisting it; note that its output includes any Secrets the chart generates.

Step 5: one command for install-or-upgrade

In scripts and CI, use helm upgrade --install: it installs the release if it does not exist and upgrades it otherwise. --create-namespace creates the namespace when installing, and --wait waits until Pods are ready (bounded by --timeout, five minutes by default) before reporting success.

helm upgrade --install web podinfo/podinfo \
  --namespace demo --create-namespace \
  -f my-values.yaml --wait

Step 6: roll back

helm history web --namespace demo
helm rollback web 1 --namespace demo

A rollback does not erase history: it creates a new revision whose contents equal the old one. Only resources managed by the chart are rolled back; data written to databases or volumes is not.

Step 7: uninstall

Warning: helm uninstall deletes every resource the release created, and with typical storage settings that includes persistent volumes. Check what will go with helm get manifest web --namespace demo first.

helm uninstall web --namespace demo

Add --keep-history if you want the release record to remain visible with helm list --uninstalled.

Helm versions

Helm 4 is the current major version and Helm 3 is in support mode. The everyday commands shown here exist in both; read the release notes before upgrading CI pipelines, because some flags changed.

Official documentation

• Using Helm
• helm upgrade