Helm Cheat Sheet
Quick reference for Helm, the package manager for Kubernetes. Covers chart structure, templating, lifecycle commands, hooks, OCI registries and common patterns.
Versions: Helm 4 (released November 2025, 4.3.x current) is the current major version; Helm 3 (3.22.x) still gets fixes. Commands below work on both unless marked. What changed in Helm 4 for CLI users:
| Helm 3 | Helm 4 |
|---|---|
--atomic | --rollback-on-failure (old name still works, with a deprecation warning) |
--force | --force-replace (old name deprecated) |
| Client-side apply (three-way merge) | Server-side apply for new releases; releases created by Helm 3 keep client-side apply unless you pass --server-side |
helm registry login https://host/path | helm registry login host (domain only) |
--post-renderer ./script.sh | --post-renderer takes a plugin name; wrap scripts as post-renderer plugins |
| — | Install by digest: oci://reg/app@sha256:... |
The examples use bitnami/... charts as familiar names. Since 2025 Bitnami's free catalog no longer receives regular image updates (most images moved to the paid Bitnami Secure Images, old ones to bitnamilegacy), so check what a chart pulls before using it in production.
Related: Kubernetes Cheat Sheet | kubectl Advanced
Repository Management
| Command | Description |
|---|---|
helm repo add bitnami https://charts.bitnami.com/bitnami | Add a chart repository |
helm repo add stable https://charts.helm.sh/stable | Add legacy stable repo (archived since 2020, no updates) |
helm repo add myrepo https://charts.example.com --username u --password-stdin | Add a private HTTP repo |
helm repo update | Update repo index |
helm repo list | List configured repos |
helm repo remove bitnami | Remove a repo |
helm search repo nginx | Search repos for a chart |
helm search repo nginx --versions | Show all available versions |
helm search hub wordpress | Search Artifact Hub |
helm search repo nginx --devel | Include pre-release versions |
helm pull bitnami/nginx --untar | Download and unpack a chart to inspect it |
OCI registries don't use helm repo add; you reference them directly with oci:// URLs (see OCI Registries).
Chart Lifecycle
Install
| Command | Description |
|---|---|
helm install my-release bitnami/nginx | Install a chart |
helm install my-release bitnami/nginx -n production | Install in specific namespace |
helm install my-release bitnami/nginx -f values.yaml | Install with custom values |
helm install my-release bitnami/nginx --set replicaCount=3 | Install with inline overrides |
helm install my-release bitnami/nginx --set-string image.tag="1.25" | Force value as string |
helm install my-release bitnami/nginx --version 15.0.0 | Install specific chart version |
helm install my-release ./my-chart | Install from local chart directory |
helm install my-release my-chart.tgz | Install from local archive |
helm install my-release bitnami/nginx --dry-run --debug | Dry run (render templates only) |
helm install my-release bitnami/nginx --dry-run=server | Dry run that also validates against the cluster (and makes lookup work) |
helm install my-release bitnami/nginx --wait --timeout 5m | Wait for resources to be ready (default timeout 5m) |
helm install my-release bitnami/nginx --create-namespace -n new-ns | Create namespace if missing |
helm install bitnami/nginx --generate-name | Let Helm pick a release name |
helm install my-release bitnami/nginx --set-file config=./app.conf | Set a value from a file's contents |
helm install my-release bitnami/nginx --set-json 'resources={"limits":{"cpu":"500m"}}' | Set a structured value as JSON |
helm install my-release bitnami/nginx --take-ownership | Adopt existing resources not created by Helm (3.17+) |
--set Syntax
| Syntax | Result in values |
|---|---|
--set a.b=1 | a: {b: 1} |
--set a=1,b=2 | Two values |
--set list={x,y} | list: [x, y] |
--set servers[0].port=80 | Index into a list |
--set name=a\,b | Escape a comma |
--set nodeSelector."kubernetes\.io/os"=linux | Key containing dots |
--set key=null | Remove a default key |
Precedence (later wins): chart values.yaml → parent chart values → -f files in order → --set/--set-string/--set-file/--set-json.
Upgrade
| Command | Description |
|---|---|
helm upgrade my-release bitnami/nginx | Upgrade a release |
helm upgrade my-release bitnami/nginx -f values-prod.yaml | Upgrade with new values |
helm upgrade my-release bitnami/nginx --reuse-values --set replicas=5 | Keep existing values, override one |
helm upgrade --install my-release bitnami/nginx | Install if not exists, upgrade if it does |
helm upgrade my-release bitnami/nginx --atomic | Auto-rollback on failure (Helm 4: --rollback-on-failure) |
helm upgrade my-release bitnami/nginx --force | Force resource update by delete-and-recreate (Helm 4: --force-replace) |
helm upgrade my-release bitnami/nginx --reset-then-reuse-values | Start from chart defaults, re-apply previous user values, then your overrides (3.14+) |
helm upgrade my-release bitnami/nginx --server-side | Use server-side apply (Helm 4) |
helm upgrade my-release bitnami/nginx --history-max 10 | Keep at most 10 revisions (default 10; 0 = unlimited) |
helm upgrade my-release bitnami/nginx --cleanup-on-fail | Delete resources created by a failed upgrade |
Typical CI deploy:
helm upgrade --install api oci://ghcr.io/myorg/charts/api --version 1.4.2 \
-n prod --create-namespace -f values-prod.yaml \
--set image.tag="$GIT_SHA" --wait --timeout 10m --atomic
WARNING
--reuse-values merges with existing values. Without it, all values reset to chart defaults plus your overrides. This catches people off guard.
Rollback
| Command | Description |
|---|---|
helm rollback my-release | Rollback to previous revision |
helm rollback my-release 3 | Rollback to specific revision |
helm rollback my-release 3 --wait | Rollback and wait for readiness |
Uninstall
| Command | Description |
|---|---|
helm uninstall my-release | Delete a release |
helm uninstall my-release -n production | Delete from specific namespace |
helm uninstall my-release --keep-history | Delete but keep history |
Inspect & Debug
| Command | Description |
|---|---|
helm list | List installed releases in current namespace |
helm list -A | List releases across all namespaces |
helm list --pending | Show pending releases |
helm status my-release | Show release status |
helm history my-release | Show release revision history |
helm get values my-release | Show user-supplied values |
helm get values my-release --all | Show all computed values |
helm get manifest my-release | Show rendered Kubernetes manifests |
helm get notes my-release | Show release notes |
helm get hooks my-release | Show release hooks |
helm show chart bitnami/nginx | Show chart metadata |
helm show values bitnami/nginx | Show default values.yaml |
helm show readme bitnami/nginx | Show chart README |
helm template my-release bitnami/nginx -f values.yaml | Render templates locally (no install) |
helm template my-release ./my-chart -s templates/deployment.yaml | Render a single template |
helm template my-release ./my-chart --api-versions monitoring.coreos.com/v1 --kube-version 1.34 | Fake cluster capabilities while rendering offline |
helm get all my-release --revision 3 | Everything about one revision |
helm list -a / helm list --failed | All releases incl. failed/pending / only failed |
helm env | Helm's paths and settings (HELM_NAMESPACE, cache, config dirs) |
helm diff upgrade my-release bitnami/nginx -f values.yaml | Preview changes before upgrading (helm-diff plugin) |
Release stuck in "another operation is in progress"
A crashed upgrade can leave the release in pending-upgrade/pending-install. Check helm history my-release, then helm rollback my-release <last-good-revision>. Release state lives in Secrets named sh.helm.release.v1.<name>.v<revision> in the release namespace.
Chart Structure
my-chart/
├── Chart.yaml # Chart metadata (name, version, dependencies)
├── Chart.lock # Locked dependency versions
├── values.yaml # Default configuration values
├── values.schema.json # JSON Schema for values validation
├── templates/
│ ├── _helpers.tpl # Template helpers and partials
│ ├── deployment.yaml
│ ├── service.yaml
│ ├── ingress.yaml
│ ├── configmap.yaml
│ ├── hpa.yaml
│ ├── serviceaccount.yaml
│ ├── NOTES.txt # Post-install instructions
│ └── tests/
│ └── test-connection.yaml
├── charts/ # Dependency chart archives
├── crds/ # Custom Resource Definitions
└── .helmignore # Files to exclude from packaging
Chart.yaml
apiVersion: v2
name: my-app
description: My application Helm chart
type: application # application or library
version: 1.2.0 # Chart version (SemVer)
appVersion: "3.5.1" # Application version
dependencies:
- name: postgresql
version: "12.x.x"
repository: "https://charts.bitnami.com/bitnami"
condition: postgresql.enabled
- name: redis
version: "17.x.x"
repository: "https://charts.bitnami.com/bitnami"
condition: redis.enabled
- name: common
version: "~2.2.0"
repository: "oci://registry-1.docker.io/bitnamicharts" # OCI dependency: no `helm repo add` needed
alias: shared # refer to its values as .Values.shared
kubeVersion: ">=1.29.0-0" # refuse to install on older clusters
version is the chart's own SemVer and must be bumped for every chart change; appVersion is informational (often used as the default image tag).
Templating Essentials
Built-in Objects
| Object | Description |
|---|---|
.Release.Name | Release name |
.Release.Namespace | Release namespace |
.Release.IsUpgrade | True if upgrade/rollback |
.Release.IsInstall | True if install |
.Release.Revision | Revision number |
.Chart.Name | Chart name |
.Chart.Version | Chart version |
.Chart.AppVersion | App version |
.Values | Values from values.yaml and overrides |
.Capabilities.KubeVersion | Kubernetes version |
.Capabilities.APIVersions.Has "networking.k8s.io/v1/Ingress" | Check whether the cluster serves an API |
.Release.Service | Always Helm |
.Files | Non-template files in the chart (.Files.Get "conf/app.ini") |
.Template.Name | Current template file path |
Common Template Functions
# String functions
name: {{ .Values.name | upper }}
name: {{ .Values.name | lower }}
name: {{ .Values.name | title }}
name: {{ .Values.name | quote }}
name: {{ .Values.name | trim }}
name: {{ .Values.name | replace "old" "new" }}
name: {{ printf "%s-%s" .Release.Name .Chart.Name }}
# Default values
image: {{ .Values.image | default "nginx:latest" }}
# Required values (fails if missing)
password: {{ required "password is required" .Values.password }}
# Conditionals
{{- if .Values.ingress.enabled }}
# ingress resources
{{- end }}
# Ternary
replicas: {{ ternary 3 1 .Values.production }}
# Loops
{{- range .Values.env }}
- name: {{ .name }}
value: {{ .value | quote }}
{{- end }}
# With (change scope)
{{- with .Values.nodeSelector }}
nodeSelector:
{{- toYaml . | nindent 2 }}
{{- end }}
# Inside range/with, "." is the item: use $ for the root context
{{- range .Values.hosts }}
- host: {{ . }}
release: {{ $.Release.Name }}
{{- end }}
# Range over a map with key/value
{{- range $key, $val := .Values.extraEnv }}
- name: {{ $key }}
value: {{ $val | quote }}
{{- end }}
# Variables
{{- $fullName := include "my-app.fullname" . }}
# Whitespace control: {{- trims before, -}} trims after
# Logic and comparison
{{- if and .Values.ingress.enabled (eq .Values.env "prod") }}
{{- if not (empty .Values.extraArgs) }}
{{- if hasKey .Values "legacy" }}
# Restart pods when a ConfigMap changes
annotations:
checksum/config: {{ include (print $.Template.BasePath "/configmap.yaml") . | sha256sum }}
# Embed files from the chart
data:
{{- (.Files.Glob "config/*").AsConfig | nindent 2 }}
app.ini: |-
{{- .Files.Get "files/app.ini" | nindent 4 }}
# Base64 for Secrets
password: {{ .Values.password | b64enc | quote }}
# Read a live object from the cluster (empty under helm template / client dry-run)
{{- $existing := lookup "v1" "Secret" .Release.Namespace "my-secret" }}
# Fail rendering with a message
{{- fail "ingress.host is required when ingress is enabled" }}
# Render a value that itself contains template syntax
{{ tpl .Values.customLabel . }}
| Function | Example |
|---|---|
toYaml / toJson / fromYaml | toYaml .Values.resources | nindent 12 |
indent vs nindent | nindent adds a newline first, so it works after key: |
default | Note default treats false and 0 as empty: use ternary or hasKey for booleans |
coalesce | First non-empty value |
list, dict, merge, get | Build and combine collections |
semverCompare | semverCompare ">=1.30-0" .Capabilities.KubeVersion.Version |
randAlphaNum | Random string (changes every upgrade unless combined with lookup) |
Helper Templates (_helpers.tpl)
{{/* Generate standard labels */}}
{{- define "my-app.labels" -}}
helm.sh/chart: {{ include "my-app.chart" . }}
app.kubernetes.io/name: {{ include "my-app.name" . }}
app.kubernetes.io/instance: {{ .Release.Name }}
app.kubernetes.io/managed-by: {{ .Release.Service }}
{{- end }}
{{/* Generate a fullname with release */}}
{{- define "my-app.fullname" -}}
{{- printf "%s-%s" .Release.Name .Chart.Name | trunc 63 | trimSuffix "-" }}
{{- end }}
{{/* Usage in templates */}}
metadata:
name: {{ include "my-app.fullname" . }}
labels:
{{- include "my-app.labels" . | nindent 4 }}
Hooks
Hooks run at specific points in the release lifecycle.
| Annotation Value | When It Runs |
|---|---|
pre-install | Before any resources are installed |
post-install | After all resources are installed |
pre-upgrade | Before any resources are upgraded |
post-upgrade | After all resources are upgraded |
pre-delete | Before any resources are deleted |
post-delete | After all resources are deleted |
pre-rollback | Before a rollback |
post-rollback | After a rollback |
test | When helm test is run |
Hook Example — Database Migration
apiVersion: batch/v1
kind: Job
metadata:
name: {{ include "my-app.fullname" . }}-migrate
annotations:
"helm.sh/hook": pre-upgrade
"helm.sh/hook-weight": "0"
"helm.sh/hook-delete-policy": hook-succeeded
spec:
template:
spec:
restartPolicy: Never
containers:
- name: migrate
image: {{ .Values.image.repository }}:{{ .Values.image.tag }}
command: ["npm", "run", "migrate"]
env:
- name: DATABASE_URL
valueFrom:
secretKeyRef:
name: {{ include "my-app.fullname" . }}-secrets
key: database-url
Hook Delete Policies
| Policy | Description |
|---|---|
hook-succeeded | Delete after hook succeeds |
hook-failed | Delete after hook fails |
before-hook-creation | Delete previous hook before launching new one (the default when no policy is set) |
Lower helm.sh/hook-weight runs first (weights are strings, can be negative). Helm waits for hook Jobs/Pods to complete before continuing; a failed hook fails the release. Use "helm.sh/resource-policy": keep on a normal resource (e.g. a PVC) to stop helm uninstall from deleting it.
Dependencies
# Update dependencies (downloads to charts/)
helm dependency update ./my-chart
# List dependencies
helm dependency list ./my-chart
# Build (download the exact versions pinned in Chart.lock)
helm dependency build ./my-chart
update resolves the ranges in Chart.yaml and rewrites Chart.lock; build reproduces what Chart.lock says (use it in CI). Parent charts set subchart values under the subchart's name (or alias), and global: values are visible to every subchart as .Values.global.
Conditional Dependencies in values.yaml
# values.yaml
postgresql:
enabled: true
auth:
postgresPassword: "secret"
database: "myapp"
redis:
enabled: false
Chart Development
# Create a new chart scaffold
helm create my-chart
# Lint a chart for errors
helm lint ./my-chart
# Lint with specific values
helm lint ./my-chart -f values-prod.yaml
# Package a chart
helm package ./my-chart
# Package with specific version
helm package ./my-chart --version 2.0.0
# Push to OCI registry
helm push my-chart-2.0.0.tgz oci://registry.example.com/charts
# Template (render locally without install)
helm template my-release ./my-chart -f values.yaml --debug
# Run chart tests
helm test my-release
# Validate rendered manifests against Kubernetes schemas (third-party)
helm template my-release ./my-chart | kubeconform -strict -summary
# Unit-test templates (helm-unittest plugin)
helm unittest ./my-chart
values.schema.json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"required": ["image"],
"properties": {
"replicaCount": { "type": "integer", "minimum": 1 },
"image": {
"type": "object",
"required": ["repository"],
"properties": { "tag": { "type": "string" } }
}
}
}
helm install, upgrade, lint and template all validate values against this file, so typos like replicas: "3" fail early.
Plugins
| Command | Description |
|---|---|
helm plugin install https://github.com/databus23/helm-diff | Install a plugin |
helm plugin list | List plugins |
helm plugin update diff | Update a plugin |
helm plugin uninstall diff | Remove a plugin |
TIP
Always run helm lint and helm template before pushing chart changes. Catch YAML errors locally, not in production.
OCI Registry Support
# Login to OCI registry (Helm 4: domain only, no https:// or path)
helm registry login registry.example.com
echo "$TOKEN" | helm registry login ghcr.io -u USER --password-stdin
# Push chart to OCI
helm push my-chart-1.0.0.tgz oci://registry.example.com/charts
# Pull chart from OCI
helm pull oci://registry.example.com/charts/my-chart --version 1.0.0
# Install from OCI
helm install my-release oci://registry.example.com/charts/my-chart --version 1.0.0
# Inspect without installing
helm show values oci://registry.example.com/charts/my-chart --version 1.0.0
# Install a pinned digest (Helm 4): fails if the content doesn't match
helm install my-release oci://registry.example.com/charts/my-chart@sha256:<digest>
# Log out
helm registry logout registry.example.com
| Registry | Push URL |
|---|---|
| GitHub Container Registry | oci://ghcr.io/<org>/charts |
| Amazon ECR | oci://<account>.dkr.ecr.<region>.amazonaws.com (login: aws ecr get-login-password | helm registry login --username AWS --password-stdin <account>.dkr.ecr.<region>.amazonaws.com) |
| Google Artifact Registry | oci://<region>-docker.pkg.dev/<project>/<repo> |
| Azure Container Registry | oci://<name>.azurecr.io/helm |
| Docker Hub | oci://registry-1.docker.io/<user> |
- The chart name and version come from the
.tgz; theoci://URL you push to is only the namespace. The pushed ref is<url>/<chart-name>:<version>. helm pushonly takes packaged.tgzfiles:helm packagefirst.--versionis required to pin; without it Helm picks the latest SemVer tag.helm repo add,helm search repoandhelm repo updatedo not work with OCI registries.
Test Yourself
-
What command installs a chart with a dry run to preview rendered templates?
helm install my-release bitnami/nginx --dry-run --debug -
How do you upgrade a release and automatically rollback if it fails?
helm upgrade my-release bitnami/nginx --atomic -
What command shows the user-supplied values of an installed release?
helm get values my-release -
How do you render templates locally without installing?
helm template my-release ./my-chart -f values.yaml -
What hook annotation runs a Job before resources are upgraded?
"helm.sh/hook": pre-upgrade -
How do you force a value to be treated as a string in
--set?--set-string image.tag="1.25" -
What does
--reuse-valuesdo during an upgrade? It merges new overrides with existing values. Without it, all values reset to chart defaults plus your overrides. -
What command checks a chart for errors before deploying?
helm lint ./my-chart -
How do you keep release history after uninstalling?
helm uninstall my-release --keep-history -
What built-in object gives you the current release name in a template?
.Release.Name
Common Gotchas
--reuse-valuessilently keeps old values. If a chart adds new required values in an upgrade,--reuse-valueswill not include them. Review chart changelogs before upgrading.- Forgetting
helm lintbefore pushing. A YAML indentation error in templates will not show up until install time. Always lint and template-render locally first. - Hook resources are not managed by the release. Hooks are created and deleted based on their delete policy. If a hook Job fails, it may linger and block future upgrades.
helm upgradewithout--installfails if the release does not exist. Usehelm upgrade --installfor idempotent CI/CD pipelines.- CRDs in
crds/are installed once and never upgraded or deleted by Helm. Upgrade CRDs yourself (kubectl apply --server-side -f crds/) or ship them as templates in a separate chart. --set image.tag=1.10becomes the number1.1. Use--set-string(or quote in a values file) for versions, booleans-as-strings and long numeric IDs.defaultswallowsfalse..Values.enabled | default trueis alwaystrue. UsehasKeyorternary.lookupreturns empty duringhelm templateand--dry-run(unless--dry-run=server), so templates must handle the empty case.- Release names are namespace-scoped; Helm commands default to the kubeconfig namespace. Forgetting
-nmakeshelm listlook empty andhelm upgrade --installcreate a second release. --atomic/--forceare deprecated in Helm 4. Switch scripts to--rollback-on-failure/--force-replaceonce all your runners are on Helm 4.
One-Liner Summary
Helm is the package manager for Kubernetes -- master install, upgrade --atomic, template, hooks, and values.yaml overrides to deploy and manage complex applications repeatably.
Last updated: 2026-11-09