Helm: The Kubernetes Package Manager, Demystified

apiVersion: v2                 # v2 = Helm 3 (v1 = Helm 2, do not use)
name: myapp
description: Production deployment chart for myapp
type: application              # "application" (default) or "library"
version: 1.4.2                 # Chart version (semver, bump on any chart change)
appVersion: "3.8.1"            # App version (informational, shown in helm list)

# Kubernetes version constraint
kubeVersion: ">= 1.25.0-0"

# Dependencies (replaces requirements.yaml from Helm 2)
dependencies:
  - name: redis
    version: "17.x"           # Semver range
    repository: "https://charts.bitnami.com/bitnami"
    condition: redis.enabled   # Toggle via values
  - name: postgresql
    version: "12.5.9"
    repository: "oci://registry-1.docker.io/bitnamicharts"
    alias: db                  # Reference as .Values.db in templates

maintainers:
  - name: Platform Team
    email: platform@company.com

{
  "$schema": "https://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["image", "replicaCount"],
  "properties": {
    "replicaCount": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "image": {
      "type": "object",
      "required": ["repository", "tag"],
      "properties": {
        "repository": { "type": "string", "minLength": 1 },
        "tag": { "type": "string", "pattern": "^[a-zA-Z0-9._-]+$" },
        "pullPolicy": { "type": "string", "enum": ["Always", "IfNotPresent", "Never"] }
      }
    }
  }
}

# if / else if / else
{{- if .Values.ingress.enabled }}
apiVersion: networking.k8s.io/v1
kind: Ingress
...
{{- end }}

# Negation
{{- if not .Values.autoscaling.enabled }}
replicas: {{ .Values.replicaCount }}
{{- end }}

# Boolean AND / OR
{{- if and .Values.metrics.enabled .Values.metrics.serviceMonitor.enabled }}
...
{{- end }}

# range (loop over list)
{{- range .Values.ingress.hosts }}
- host: {{ .host | quote }}
  http:
    paths:
      {{- range .paths }}
      - path: {{ .path }}
        pathType: {{ .pathType }}
      {{- end }}
{{- end }}

# range (loop over map with $key, $value)
{{- range $key, $value := .Values.env }}
- name: {{ $key }}
  value: {{ $value | quote }}
{{- end }}

# with (change scope — BEWARE: . is rebound)
{{- with .Values.nodeSelector }}
nodeSelector:
  {{- toYaml . | nindent 2 }}
{{- end }}

# Access parent scope inside with/range using $
{{- with .Values.tolerations }}
tolerations:
  {{- toYaml . | nindent 2 }}
# Still need release name? Use $.Release.Name ($ = root scope)
{{- end }}

{{/* Generate standard labels */}}
{{- define "mychart.labels" -}}
helm.sh/chart: {{ include "mychart.chart" . }}
app.kubernetes.io/name: {{ include "mychart.name" . }}
app.kubernetes.io/instance: {{ .Release.Name }}
app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
app.kubernetes.io/managed-by: {{ .Release.Service }}
{{- end }}

{{/* Generate selector labels (subset of above — must be immutable) */}}
{{- define "mychart.selectorLabels" -}}
app.kubernetes.io/name: {{ include "mychart.name" . }}
app.kubernetes.io/instance: {{ .Release.Name }}
{{- end }}

{{/* Chart name + version for chart label */}}
{{- define "mychart.chart" -}}
{{ printf "%s-%s" .Chart.Name .Chart.Version | replace "+" "_" | trunc 63 | trimSuffix "-" }}
{{- end }}

{{/* Fullname: release-chart, truncated to 63 chars */}}
{{- define "mychart.fullname" -}}
{{- if .Values.fullnameOverride }}
{{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" }}
{{- else }}
{{- printf "%s-%s" .Release.Name .Chart.Name | trunc 63 | trimSuffix "-" }}
{{- end }}
{{- end }}

# Multiple value files (later files override earlier)
helm upgrade --install myapp ./chart \
  -f values.yaml \
  -f values-prod.yaml \
  -f values-secrets.yaml

# --set overrides everything (careful with complex values)
helm upgrade --install myapp ./chart \
  -f values-prod.yaml \
  --set image.tag=abc123 \
  --set replicaCount=5

# --set with special characters
--set ingress.hosts[0].host=api.example.com       # Array index
--set nodeSelector."kubernetes\.io/os"=linux       # Escaped dots in keys
--set config.data="line1\nline2"                   # Newlines

# --set-string forces string type (avoids YAML type coercion)
--set-string image.tag=1.0                         # "1.0" not 1.0 (float)
--set-string enabled=true                          # "true" not true (bool)

# --set-json for complex structures
--set-json 'tolerations=[{"key":"dedicated","operator":"Equal","value":"gpu"}]'

# View final merged values for a deployed release
helm get values myapp -n production
helm get values myapp -n production --all           # Include defaults

# Download dependencies into charts/ based on Chart.yaml
helm dependency update ./mychart

# Rebuild charts/ from Chart.lock (for CI reproducibility)
helm dependency build ./mychart

# List current dependency state
helm dependency list ./mychart

# Typical CI workflow:
# 1. Developer runs: helm dependency update (updates Chart.lock)
# 2. Commit both Chart.yaml and Chart.lock
# 3. CI runs: helm dependency build (uses locked versions)

# Values for this chart
replicaCount: 3
image:
  repository: myapp
  tag: "2.0.0"

# Values for the "redis" dependency (key matches dependency name)
redis:
  enabled: true
  architecture: standalone
  auth:
    enabled: true
    password: "override-me-with-secret"
  master:
    resources:
      requests:
        cpu: 100m
        memory: 128Mi

# Values for the "postgresql" dependency (using alias "db")
db:
  enabled: true
  auth:
    postgresPassword: "override-me"
    database: myapp

# Global values (accessible to ALL charts and subcharts as .Values.global)
global:
  imagePullSecrets:
    - name: regcred
  storageClass: gp3-encrypted

# The canonical production upgrade command
helm upgrade --install myapp ./chart \
  --namespace production \
  --create-namespace \
  --values values-prod.yaml \
  --set image.tag=${GIT_SHA} \
  --atomic \                    # Auto-rollback on failure
  --timeout 10m \               # Max wait for readiness
  --wait                        # Wait for all resources ready

# --atomic implies --wait and --cleanup-on-fail:
#   - If upgrade fails → rollback to previous revision
#   - If install fails → delete the failed release entirely
#   - This is the single most important flag for CI/CD safety

# List all releases across namespaces
helm list -A
helm list -A --filter 'myapp'

# Release history (revisions, status, timestamps)
helm history myapp -n production

# Get the values used for the current release
helm get values myapp -n production
helm get values myapp -n production --all        # Including defaults
helm get values myapp -n production --revision 5  # Specific revision

# Get the rendered manifests from a deployed release
helm get manifest myapp -n production

# Get everything (values + manifest + notes + hooks)
helm get all myapp -n production

# Compare two revisions (requires helm-diff plugin)
helm diff revision myapp 6 7 -n production

apiVersion: batch/v1
kind: Job
metadata:
  name: {{ include "mychart.fullname" . }}-migrate
  labels:
    {{- include "mychart.labels" . | nindent 4 }}
  annotations:
    "helm.sh/hook": pre-upgrade,pre-install
    "helm.sh/hook-weight": "-5"            # Lower weight runs first
    "helm.sh/hook-delete-policy": before-hook-creation,hook-succeeded
spec:
  backoffLimit: 1
  activeDeadlineSeconds: 300
  template:
    spec:
      restartPolicy: Never
      containers:
      - name: migrate
        image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
        command: ["./migrate", "--target", "latest"]
        env:
        - name: DATABASE_URL
          valueFrom:
            secretKeyRef:
              name: db-credentials
              key: url

# Render all templates locally (no cluster required)
helm template myapp ./chart -f values-prod.yaml

# Render a single template
helm template myapp ./chart --show-only templates/deployment.yaml

# Render with debug output (shows computed values + template errors)
helm template myapp ./chart -f values-prod.yaml --debug

# Dry run against the cluster (validates API server side)
helm upgrade --install myapp ./chart -f values-prod.yaml --dry-run

# Dry-run with server-side validation (catches more errors)
helm upgrade --install myapp ./chart -f values-prod.yaml --dry-run=server

# Lint the chart (catches structure + template issues)
helm lint ./chart -f values-prod.yaml --strict

# Compare current vs new (requires helm-diff plugin)
helm diff upgrade myapp ./chart -f values-prod.yaml -n production

# Check release status
helm status myapp -n production

# View history — look for FAILED or PENDING_UPGRADE
helm history myapp -n production
# REVISION  STATUS          DESCRIPTION
# 5         deployed        Upgrade complete
# 6         failed          Upgrade "myapp" failed: timed out
# 7         deployed        Rollback to 5

# Get the manifest that was applied
helm get manifest myapp -n production --revision 6

# Get the values that were used for the failed revision
helm get values myapp -n production --revision 6

# Compare values between revisions
diff <(helm get values myapp -n prod --revision 5) \
     <(helm get values myapp -n prod --revision 6)

# Check Kubernetes events for the namespace
kubectl get events -n production --sort-by='.lastTimestamp' | tail -30

# Check pod status
kubectl get pods -n production -l app.kubernetes.io/instance=myapp

# Option 1: Rollback to last good revision
helm rollback myapp 0 -n production        # 0 = previous revision

# Option 2: If rollback also fails, manually patch the release secret
# Find the stuck release secret
kubectl get secrets -n production -l owner=helm,name=myapp

# The latest secret will have status "pending-upgrade" or "pending-install"
# Patch it to "failed" so Helm can proceed
kubectl patch secret sh.helm.release.v1.myapp.v8 -n production \
  --type=merge -p '{"metadata":{"labels":{"status":"failed"}}}'

# Then retry the upgrade
helm upgrade --install myapp ./chart -f values.yaml -n production --atomic

# Option 3: Nuclear — uninstall and reinstall (loses history)
helm uninstall myapp -n production
helm install myapp ./chart -f values.yaml -n production

spec:
  template:
    metadata:
      annotations:
        # Rollout when ConfigMap changes
        checksum/config: {{ include (print $.Template.BasePath "/configmap.yaml") . | sha256sum }}
        # Rollout when Secret changes
        checksum/secret: {{ include (print $.Template.BasePath "/secret.yaml") . | sha256sum }}

# Fail at render time, not at deploy time
image: "{{ required "image.repository is required" .Values.image.repository }}:{{ required "image.tag is required" .Values.image.tag }}"

# Useful error message in helm template output:
# Error: execution error at (mychart/templates/deployment.yaml:25):
#   image.tag is required

# Embed a config file as ConfigMap data
apiVersion: v1
kind: ConfigMap
metadata:
  name: {{ include "mychart.fullname" . }}-config
data:
  # Single file
  nginx.conf: |-
    {{ .Files.Get "files/nginx.conf" | nindent 4 }}
  # All files matching a glob
  {{- range $path, $_ := .Files.Glob "files/configs/*.yaml" }}
  {{ base $path }}: |-
    {{ $.Files.Get $path | nindent 4 }}
  {{- end }}

# Embed as a Secret (auto base64 encoded)
apiVersion: v1
kind: Secret
metadata:
  name: {{ include "mychart.fullname" . }}-certs
type: Opaque
data:
  {{- (.Files.Glob "certs/*").AsSecrets | nindent 2 }}

# Use the right API version based on cluster capabilities
{{- if .Capabilities.APIVersions.Has "autoscaling/v2" }}
apiVersion: autoscaling/v2
{{- else }}
apiVersion: autoscaling/v2beta2
{{- end }}
kind: HorizontalPodAutoscaler

# Check minimum Kubernetes version
{{- if semverCompare ">= 1.25-0" .Capabilities.KubeVersion.GitVersion }}
# Use PodDisruptionBudget policy/v1
{{- end }}

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: {{ include "mychart.fullname" . }}-data
  annotations:
    "helm.sh/resource-policy": keep      # Helm will NOT delete this on uninstall
spec:
  accessModes: [ReadWriteOnce]
  resources:
    requests:
      storage: 100Gi

# Chart.yaml of the library chart
apiVersion: v2
name: common-templates
type: library                  # Cannot be installed directly
version: 1.0.0

# Chart.yaml of the consuming chart
dependencies:
  - name: common-templates
    version: "1.x"
    repository: "oci://registry.example.com/charts"

# Use in templates:
{{- include "common-templates.labels" . | nindent 4 }}
{{- include "common-templates.deployment" . }}

repositories:
  - name: bitnami
    url: https://charts.bitnami.com/bitnami
  - name: ingress-nginx
    url: https://kubernetes.github.io/ingress-nginx
  - name: prometheus
    url: https://prometheus-community.github.io/helm-charts

# Environment-specific values
environments:
  dev:
    values:
      - env/defaults.yaml
      - env/dev.yaml
  staging:
    values:
      - env/defaults.yaml
      - env/staging.yaml
  production:
    values:
      - env/defaults.yaml
      - env/production.yaml

# Helm defaults applied to all releases
helmDefaults:
  atomic: true
  timeout: 600
  wait: true
  createNamespace: true

# Release definitions
releases:
  - name: ingress-nginx
    namespace: ingress
    chart: ingress-nginx/ingress-nginx
    version: 4.8.3
    values:
      - values/ingress.yaml

  - name: prometheus
    namespace: monitoring
    chart: prometheus/kube-prometheus-stack
    version: 55.5.0
    values:
      - values/prometheus.yaml
      - values/prometheus-{{ .Environment.Name }}.yaml

  - name: myapp
    namespace: {{ .Environment.Name }}
    chart: ./charts/myapp
    values:
      - values/myapp.yaml
      - values/myapp-{{ .Environment.Name }}.yaml
    set:
      - name: image.tag
        value: {{ env "IMAGE_TAG" | default "latest" }}
    needs:                          # Dependency ordering
      - ingress/ingress-nginx

# Diff all releases against live cluster
helmfile -e production diff

# Apply all releases (install/upgrade)
helmfile -e production apply

# Apply only specific releases
helmfile -e production -l name=myapp apply

# Sync (apply without diff confirmation)
helmfile -e production sync

# Destroy all releases
helmfile -e staging destroy

# Template locally (no cluster)
helmfile -e production template

# Lint all charts
helmfile -e production lint

# ---- Deploy ----
helm upgrade --install NAME CHART -f values.yaml -n NS --atomic --timeout 10m

# ---- Inspect ----
helm list -A                          # All releases
helm status NAME -n NS                # Release status
helm get values NAME -n NS --all      # Effective values
helm get manifest NAME -n NS          # Rendered manifests
helm history NAME -n NS               # Revision history

# ---- Debug ----
helm template NAME CHART -f values.yaml --debug     # Render locally
helm lint CHART -f values.yaml --strict              # Validate chart
helm diff upgrade NAME CHART -f values.yaml -n NS   # Preview changes

# ---- Recover ----
helm rollback NAME REVISION -n NS    # Rollback
helm rollback NAME 0 -n NS           # Rollback to previous

# ---- Clean ----
helm uninstall NAME -n NS            # Delete release
helm uninstall NAME -n NS --keep-history  # Delete but keep history