← All cheatsheets

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.

Docs-checkedhelmkuberneteschartsreleasesvalues

Quick reference — reach for these first

Add repohelm repo add REPO URLRegister a chart repo, then helm repo update to pull its index
Deploy/upgradehelm upgrade --install REL REPO/CHART -n NSIdempotent: installs if absent, upgrades if present — the one command to use in CI
Preview YAMLhelm template REL REPO/CHART -f values.yamlRender templates locally to stdout — no cluster, no release recorded
Roll backhelm rollback REL REVISION -n NSRevert to a prior revision; omit REVISION to go to the previous one
List releaseshelm list -AShow releases across all namespaces with revision and status

Safe deploy pipeline: preview → dry-run → upgrade → (if bad) rollback

Helm safe deploy and rollback pipelineChart feeds helm template preview, then a server dry-run, then the real atomic upgrade to the cluster recording revision N, with a rollback arrow returning to a prior revision.ChartChart.yamltemplates/ + valueshelm templatepreview YAML · no clusterupgrade --install--dry-run=serversimulate on clusterupgrade --install--atomic --waitapplies for realClusterrevision Nif bad: helm rollback REL N-1

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 & previewDeploy & upgradeInspect & roll back
Add a chart repositoryhelm repo add bitnami https://charts.bitnami.com/bitnamihelm repo list shows the repo
Refresh repo indexeshelm repo update"Update Complete. ⎈Happy Helming!⎈" printed
Find a chart and its versionshelm search repo nginx --versionsRows of NAME / CHART VERSION / APP VERSION listed
Preview rendered manifests (no cluster)helm template web bitnami/nginx -f values.yamlValid multi-doc YAML to stdout; no template errors
Lint a local charthelm lint ./mychart"0 chart(s) failed" at the end
Server-side dry run before applyinghelm upgrade --install web bitnami/nginx -n web --dry-run=serverRendered 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.3helm get values web -n web shows image.tag: 1.27.3
List releases across namespaceshelm list -ARelease row with REVISION and STATUS: deployed
Check a release's status and resourceshelm status web -n webSTATUS: deployed and the deployed resources listed
View revision historyhelm history web -n webOne 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 dependencieshelm dependency update ./mychartcharts/ 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

1
Preview the rendered YAML locally — no cluster is touched, nothing is recorded
helm template web bitnami/nginx -f values.yaml | head -n 20
# apiVersion: apps/v1
# kind: Deployment
#   image: docker.io/bitnami/nginx:1.27.3
2
Server-side dry run to catch admission/schema errors before applying
helm upgrade --install web bitnami/nginx -n web --create-namespace -f values.yaml --dry-run=server
# STATUS: pending-install
# (manifest printed, no server errors)
3
Real install/upgrade (prod-changing); --atomic auto-rolls-back if it fails, --wait blocks until ready
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)
4
Verify the rollout landed
helm status web -n web && kubectl get pods -n web
# STATUS: deployed
# web-nginx-...  1/1  Running
5
Push a bad change (nonexistent image tag) so the pods fail to pull
helm 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)
6
Roll back to the known-good revision 1
helm rollback web 1 -n web --wait
# Rollback was a success! Happy Helming!
7
VERIFY — history shows a new revision that restored revision 1, and pods are healthy
helm history web -n web
# 3  ...  deployed  Rollback to 1
# kubectl get pods -n web -> 1/1 Running

Troubleshooting — symptom → first check → next check

SymptomFirst checkEstablishesNext check
helm upgrade hangs or errors; release stuck in pending-upgrade / pending-installhelm history REL -n NSWhether 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 themInstall/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 effecthelm get values REL -n NSThe exact merged values Helm used, so you can see precedence actually appliedFix 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 failureGuard 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 usehelm list -A --allWhether 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/confighelm get manifest REL -n NS | grep -A2 imageWhether 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.