Helm Cheatsheet

helm version

my-chart/
├── Chart.yaml              # Chart metadata (name, version, description)
├── values.yaml             # Default configuration values
├── values.schema.json      # JSON schema that validates values
├── templates/              # Kubernetes manifest templates
│   ├── deployment.yaml
│   ├── service.yaml
│   ├── configmap.yaml
│   └── _helpers.tpl        # Template helpers (prefixed with _)
├── charts/                 # Dependency charts (optional)
├── crds/                   # CRDs, installed before the templates (never upgraded by Helm)
├── templates/NOTES.txt     # Text printed after install/upgrade (a template too)
├── .helmignore             # Files left out of the package
└── README.md               # Documentation

mkdir -p ~/helm-charts/{metrics-server,nginx,postgres}
helm pull metrics-server/metrics-server --destination ~/helm-charts/metrics-server --untar
helm pull bitnami/nginx --destination ~/helm-charts/nginx --untar
helm pull bitnami/postgresql --destination ~/helm-charts/postgres --untar

# Backup a single release
helm get all metrics-server -n kube-system > backup-metrics-server.yaml

# Backup all releases across all namespaces (helm get needs each release's namespace)
helm list -A -o json | jq -r '.[] | "\(.name) \(.namespace)"' | while read -r name ns; do
  helm get all "$name" -n "$ns" > "backup-$ns-$name.yaml"
done

# Set custom cache directory
export HELM_CACHE_HOME=~/my-custom-helm-cache

# Set custom config directory
export HELM_CONFIG_HOME=~/.config/helm

# Set custom data directory
export HELM_DATA_HOME=~/.local/share/helm

# Enable debug logging
export HELM_DEBUG=true

# Set default namespace for all Helm commands
export HELM_NAMESPACE=production

# Set OCI registry config path
export HELM_REGISTRY_CONFIG="${HOME}/.docker/config.json"

# Make permanent (add to ~/.bash_profile or ~/.zshrc)
echo 'export HELM_CACHE_HOME=~/my-custom-helm-cache' >> ~/.bash_profile

# Download and extract chart (pin the version: without it you get the latest, 3.14.0 in October 2026)
helm pull metrics-server/metrics-server --version 3.12.2 --untar --destination ~/my-custom-charts

# Navigate to chart
cd ~/my-custom-charts/metrics-server

# Modify values or templates
vim values.yaml
vim templates/deployment.yaml

# Create custom chart package
cd ..
helm package metrics-server
# Creates: metrics-server-3.12.2.tgz

# Install custom chart
helm install metrics-server ./metrics-server-3.12.2.tgz

apiVersion: v2
name: app
version: 0.1.0
dependencies:
  - name: redis
    version: 18.0.0
    repository: https://charts.bitnami.com/bitnami
    condition: redis.enabled

# Reuse previous values, add a tweak
helm upgrade metrics-server metrics-server/metrics-server --reuse-values --set newEnv=production

# Override entirely — no old values retained
helm upgrade metrics-server metrics-server/metrics-server --reset-values --set newKey=newValue

# Reset to defaults then merge old values back
helm upgrade metrics-server metrics-server/metrics-server --reset-then-reuse-values --set version=2.0

# Save current values
helm get values my-release -o yaml > prev-values.yaml

# Upgrade with saved values as base (gets new chart defaults + your overrides)
helm upgrade my-release my-chart -f prev-values.yaml --set newKey=newValue

helm install metrics-server ./metrics-server \
  --values values-base.yaml \
  --values values-prod.yaml \
  --values values-secrets.yaml

# Inject sensitive values from files (avoid inline secrets)
helm upgrade metrics-server ./metrics-server --set-file db.password=./secrets/db_password.txt

{
  "$schema": "https://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["image"],
  "properties": {
    "replicaCount": { "type": "integer", "minimum": 1 },
    "image": {
      "type": "object",
      "required": ["repository"],
      "properties": {
        "repository": { "type": "string" },
        "pullPolicy": { "type": "string", "enum": ["Always", "IfNotPresent", "Never"] }
      }
    }
  }
}

# chart-testing tool automatically tests all ci/*.yaml files
ct lint --charts ./my-chart
ct install --charts ./my-chart

# Or manually test with specific values files
helm lint ./my-chart -f ./my-chart/ci/default-values.yaml
helm install test-release ./my-chart -f ./my-chart/ci/minimal-values.yaml --dry-run

apiVersion: batch/v1
kind: Job
metadata:
  name: "{{ include "app.fullname" . }}-migrate"
  annotations:
    "helm.sh/hook": pre-install,pre-upgrade
    "helm.sh/hook-weight": "-5"
    "helm.sh/hook-delete-policy": before-hook-creation,hook-succeeded
spec:
  template:
    spec:
      restartPolicy: Never
      containers:
      - name: migrate
        image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
        command: ["./migrate.sh"]

# templates/tests/test-conn.yaml
apiVersion: v1
kind: Pod
metadata:
  name: "{{ include "app.fullname" . }}-test"
  annotations:
    "helm.sh/hook": test
spec:
  containers:
    - name: curl
      image: curlimages/curl
      args: ["-fsS", "http://{{ include "app.fullname" . }}"]
  restartPolicy: Never

helm test metrics-server --logs

# Conditionals
{{- if .Values.hpa.enabled }}
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
...
{{- end }}

# Loops and defaults
{{- range $k, $v := .Values.extraEnv }}
- name: {{ $k }}
  value: {{ $v | quote }}
{{- end }}

# Default values
{{- $replicas := default 2 .Values.replicaCount -}}

# Helper templates (_helpers.tpl)
{{- define "app.fullname" -}}
{{- printf "%s-%s" .Release.Name .Chart.Name | trunc 63 | trimSuffix "-" -}}
{{- end -}}

# Fail early with a clear message when a value is missing
image: "{{ .Values.image.repository }}:{{ required "image.tag is required" .Values.image.tag }}"
#   Error: execution error at (p/templates/deploy.yaml:15:52): image.tag is required

# A map or list from values, indented to fit (nindent adds the newline first)
resources:
  {{- toYaml .Values.resources | nindent 12 }}

# Render a template stored in a value: greeting: "Hello from {{ .Release.Name }}"
greeting: {{ tpl .Values.greeting . | quote }}            # "Hello from r"

# Files from the chart (files/app.properties, files/*.conf) into a ConfigMap
data:
  app.properties: |-
{{ .Files.Get "files/app.properties" | indent 4 }}
{{ (.Files.Glob "files/*.conf").AsConfig | indent 2 }}

# Restart the pods when the ConfigMap changes (a Deployment doesn't do that by itself)
spec:
  template:
    metadata:
      annotations:
        checksum/config: {{ include (print $.Template.BasePath "/cm.yaml") . | sha256sum }}

{{- $ns := lookup "v1" "Namespace" "" "kube-system" }}
existing: {{ if $ns }}{{ $ns.metadata.name | quote }}{{ else }}"not-found"{{ end }}

# 1. Update repos
helm repo update

# 2. Check installed
helm list -A

# 3. Check available versions
helm search repo metrics-server/metrics-server --versions

# 4. Compare values between versions
helm show values metrics-server/metrics-server --version 3.12.0 > old-values.yaml
helm show values metrics-server/metrics-server --version 3.12.2 > new-values.yaml
diff old-values.yaml new-values.yaml

# Deploy blue (v1)
helm install my-app-blue ./my-app \
  --set image.tag=v1 \
  --namespace production

# Deploy green (v2)
helm install my-app-green ./my-app \
  --set image.tag=v2 \
  --namespace production

# Switch traffic (via service selector or ingress)
kubectl patch service my-app -p '{"spec":{"selector":{"version":"green"}}}'

# Cleanup blue when stable
helm uninstall my-app-blue --namespace production

# Deploy stable version
helm install my-app ./my-app \
  --set replicaCount=3 \
  --set image.tag=stable

# Deploy canary with 1 replica
helm install my-app-canary ./my-app \
  --set replicaCount=1 \
  --set image.tag=canary

# Monitor canary metrics
kubectl top pods -l app=my-app

# Promote canary to stable
helm upgrade my-app ./my-app \
  --set image.tag=canary \
  --reuse-values

# Remove canary
helm uninstall my-app-canary

# Key names are chart-specific: these are the metrics-server chart's (check with helm show values)
helm upgrade metrics-server metrics-server/metrics-server -n kube-system \
  --set replicas=2 \
  --set podDisruptionBudget.enabled=true \
  --set podDisruptionBudget.minAvailable=1 \
  --set updateStrategy.type=RollingUpdate \
  --set updateStrategy.rollingUpdate.maxUnavailable=0 \
  --wait --timeout 10m

helm upgrade --install metrics-server metrics-server/metrics-server \
  --namespace kube-system \
  --create-namespace \
  --values values-prod.yaml \
  --wait \
  --timeout 10m \
  --atomic          # Helm 4: --rollback-on-failure

# Development
helm upgrade --install metrics-server metrics-server/metrics-server -n dev --values values-dev.yaml

# Staging
helm upgrade --install metrics-server metrics-server/metrics-server -n staging --values values-staging.yaml

# Production
helm upgrade --install metrics-server metrics-server/metrics-server -n production --values values-prod.yaml

Error: INSTALLATION FAILED: Unable to continue with install: ClusterRole "system:metrics-server-aggregated-reader" in namespace "" exists and cannot be imported into the current release: invalid ownership metadata; annotation validation error: key "meta.helm.sh/release-namespace" must equal "kube-system": current value is "default"

Error: INSTALLATION FAILED: Unable to continue with install: ConfigMap "app-config" in namespace "own" exists and cannot be imported into the current release: invalid ownership metadata; label validation error: missing key "app.kubernetes.io/managed-by": must be set to "Helm"; annotation validation error: missing key "meta.helm.sh/release-name": must be set to "own"; annotation validation error: missing key "meta.helm.sh/release-namespace": must be set to "own"

kubectl annotate configmap app-config -n own meta.helm.sh/release-name=own meta.helm.sh/release-namespace=own
kubectl label configmap app-config -n own app.kubernetes.io/managed-by=Helm
helm install own ./own -n own

helm install own ./own -n own --take-ownership                       # Helm 3
helm install own ./own -n own --take-ownership --force-conflicts     # Helm 4

Error: INSTALLATION FAILED: create: failed to create: Secret "sh.helm.release.v1.big.v1" is invalid: data: Too long: may not be more than 1048576 bytes

# "another operation (install/upgrade/rollback) is in progress"
helm history metrics-server -n kube-system           # last revision: pending-install / pending-upgrade
helm rollback metrics-server -n kube-system          # pending-upgrade or pending-rollback: back to the last good revision
helm uninstall metrics-server -n kube-system         # pending-install: there is nothing to roll back to

# Resource conflicts
kubectl get all -l app.kubernetes.io/managed-by=Helm

# Uninstall without running hooks (e.g. a pre-delete hook that hangs)
helm uninstall metrics-server -n kube-system --no-hooks

# Last resort: forget the release (removes Helm's records, not the Kubernetes resources)
kubectl delete secret -n kube-system -l owner=helm,name=metrics-server

# Add to ~/.bashrc or ~/.zshrc
alias h='helm'
alias hls='helm list'
alias hlsa='helm list --all-namespaces'
alias hs='helm status'
alias hi='helm install'
alias hu='helm upgrade'
alias hr='helm rollback'
alias hd='helm delete'
alias ht='helm template'
alias hg='helm get'

export HELM_NAMESPACE=production    # Set default namespace
export HELM_CACHE_HOME=~/my-cache  # Set cache directory
export KUBECONFIG=~/.kube/config   # Set kubeconfig