Containers
Helm — charts, releases, and templating Kubernetes
Deep reference for Helm: what a chart is (Chart.yaml + templates + values), managing repos, safe install/upgrade/rollback with helm upgrade --install, values precedence, previewing rendered YAML with helm template, release history, dry-runs, and chart dependencies.
Quick reference — reach for these first
helm repo add REPO URLRegister a chart repo, then helm repo update to pull its indexhelm upgrade --install REL REPO/CHART -n NSIdempotent: installs if absent, upgrades if present — the one command to use in CIhelm template REL REPO/CHART -f values.yamlRender templates locally to stdout — no cluster, no release recordedhelm rollback REL REVISION -n NSRevert to a prior revision; omit REVISION to go to the previous onehelm list -AShow releases across all namespaces with revision and statusSafe deploy pipeline: preview → dry-run → upgrade → (if bad) rollback
Text equivalent: A left-to-right pipeline. A Chart (Chart.yaml plus templates plus values) feeds helm template, which previews rendered YAML with no cluster. That feeds helm upgrade --install --dry-run=server, a server-side simulation. That feeds the real helm upgrade --install --atomic, which writes to the Kubernetes cluster and records release revision N. A curved return arrow labelled helm rollback REL N-1 goes from the cluster back to a prior revision when the upgrade is bad.
Common tasks
Repos & preview · Deploy & upgrade · Inspect & roll back
| Repos & preview | Deploy & upgrade | Inspect & roll back |
|---|---|---|
| Add a chart repository | helm repo add bitnami https://charts.bitnami.com/bitnami | helm repo list shows the repo |
| Refresh repo indexes | helm repo update | "Update Complete. ⎈Happy Helming!⎈" printed |
| Find a chart and its versions | helm search repo nginx --versions | Rows of NAME / CHART VERSION / APP VERSION listed |
| Preview rendered manifests (no cluster) | helm template web bitnami/nginx -f values.yaml | Valid multi-doc YAML to stdout; no template errors |
| Lint a local chart | helm lint ./mychart | "0 chart(s) failed" at the end |
| Server-side dry run before applying | helm upgrade --install web bitnami/nginx -n web --dry-run=server | Rendered manifest printed, STATUS: pending-install, no server errors |
| Deploy or upgrade a release [PROD-CHANGING] | helm upgrade --install web bitnami/nginx -n web --create-namespace -f values.yaml --atomic --wait | "STATUS: deployed"; on failure --atomic auto-rolls back |
| Override values ad hoc (--set wins over -f) | helm upgrade --install web bitnami/nginx -n web --set image.tag=1.27.3 | helm get values web -n web shows image.tag: 1.27.3 |
| List releases across namespaces | helm list -A | Release row with REVISION and STATUS: deployed |
| Check a release's status and resources | helm status web -n web | STATUS: deployed and the deployed resources listed |
| View revision history | helm history web -n web | One row per revision with status (deployed/superseded/failed) |
| Roll back to a known-good revision [PROD-CHANGING] | helm rollback web 1 -n web --wait | "Rollback was a success! Happy Helming!" |
| Build/pin chart dependencies | helm dependency update ./mychart | charts/ populated with .tgz deps and Chart.lock written |
| Uninstall a release [PROD-DESTRUCTIVE] | helm uninstall web -n web | "release "web" uninstalled"; helm list -A no longer lists it |
Deploy and upgrade a release safely, then roll back a bad change
deploy-upgrade-rollback
helm template web bitnami/nginx -f values.yaml | head -n 20
# apiVersion: apps/v1
# kind: Deployment
# image: docker.io/bitnami/nginx:1.27.3helm upgrade --install web bitnami/nginx -n web --create-namespace -f values.yaml --dry-run=server
# STATUS: pending-install
# (manifest printed, no server errors)helm upgrade --install web bitnami/nginx -n web -f values.yaml --atomic --wait
# Release "web" has been installed. Happy Helming!
# STATUS: deployed REVISION: 1 ("upgraded" wording appears from REVISION 2 on)helm status web -n web && kubectl get pods -n web
# STATUS: deployed
# web-nginx-... 1/1 Runninghelm upgrade web bitnami/nginx -n web --set image.tag=does-not-exist --wait --timeout 60s
# Error: UPGRADE FAILED: timed out waiting; pods ImagePullBackOff
# (revision 2 recorded as failed)helm rollback web 1 -n web --wait
# Rollback was a success! Happy Helming!helm history web -n web
# 3 ... deployed Rollback to 1
# kubectl get pods -n web -> 1/1 RunningTroubleshooting — symptom → first check → next check
| Symptom | First check | Establishes | Next check |
|---|---|---|---|
| helm upgrade hangs or errors; release stuck in pending-upgrade / pending-install | helm history REL -n NS | Whether the last revision is stuck pending-* because a prior upgrade was interrupted (e.g. Ctrl-C) | helm rollback REL <last-deployed-revision> -n NS to clear it; if none is good, helm uninstall then reinstall. Never kill an in-flight upgrade. |
| CRDs missing — install fails with "no matches for kind ..." or "resource mapping not found" | kubectl get crds | grep <group> | Whether the chart's CRDs are present; Helm applies crds/ once at install and does NOT upgrade or reconcile them | Install/upgrade CRDs out of band (kubectl apply -f the chart's crds), then re-run helm upgrade --install. |
| Values from -f or --set are not taking effect | helm get values REL -n NS | The exact merged values Helm used, so you can see precedence actually applied | Fix ordering — later -f overrides earlier -f, and --set overrides -f. Re-check with helm template --debug. |
| Template render error: parse error or "nil pointer evaluating interface {}" | helm template ./chart --debug (or helm lint) | Which template file/line fails and what rendered before the failure | Guard missing keys with {{ .Values.x | default "..." }} or required; fix indentation; re-run helm lint. |
| Error: INSTALLATION FAILED: cannot re-use a name that is still in use | helm list -A --all | Whether a release of that name already exists in any status (including failed) | Use helm upgrade --install instead of helm install, or helm uninstall the old release first. |
| Upgrade reports deployed but pods still run the old image/config | helm get manifest REL -n NS | grep -A2 image | Whether the rendered manifest actually carries the new value (vs the override never reaching the field) | Confirm the --set path matches the chart's values schema; then kubectl rollout status deploy/NAME -n NS. |