Skip to content

Helm Debugging Decision Flow

Systematic approach to diagnosing Helm release issues.

START: Helm release problem
  |
  v
[1] STATUS
  helm list -n <ns>
  helm status <release> -n <ns>
  |
  +-- DEPLOYED but pods broken? --> [2] INVESTIGATE PODS
  +-- FAILED?                   --> [3] HISTORY + ROLLBACK
  +-- PENDING-UPGRADE?          --> [3] HISTORY + ROLLBACK
  +-- Not found?                --> helm install (not upgrade)
  |
  v

[2] INVESTIGATE PODS
  kubectl get pods -n <ns>
  kubectl describe pod -n <ns> <pod>
  kubectl logs -n <ns> <pod>
  |
  +-- Image wrong?     --> check values file, fix, helm upgrade
  +-- Config wrong?    --> helm get values, compare with expected
  +-- Template wrong?  --> [4] TEMPLATE DEBUG
  |
  v

[3] HISTORY + ROLLBACK
  helm history <release> -n <ns>
  |
  +-- Previous revision healthy? --> helm rollback <release> <rev> -n <ns>
  +-- All revisions broken?      --> [4] TEMPLATE DEBUG
  |
  After rollback:
  helm status <release> -n <ns>        # verify DEPLOYED
  kubectl get pods -n <ns>              # verify Running
  |
  Then investigate root cause:
  helm get values <release> -n <ns>     # current values
  diff with intended values file
  |
  v

[4] TEMPLATE DEBUG
  helm template <release> <chart> -f <values> --debug
  |
  +-- Rendering error?    --> fix template syntax
  +-- Missing CRD?        --> install CRD first
  +-- Wrong values?       --> fix values file
  |
  After fix:
  helm upgrade <release> <chart> -n <ns> -f <values> --wait
  |
  v

[5] VERIFY
  helm status <release> -n <ns>    # DEPLOYED
  kubectl get pods -n <ns>          # all Running
  helm test <release> -n <ns>       # if tests defined

Common Helm Issues

Issue Diagnostic Fix
Bad values broke release helm history shows FAILED helm rollback <release> 0
Template rendering error helm template --debug shows error Fix template syntax
Release stuck PENDING helm list shows pending-upgrade helm rollback or kubectl delete secret -l status=pending-upgrade
Values drift from Git helm get values vs values file helm upgrade -f <correct-values>
CRD not installed Template references unknown resource Install CRD, then upgrade

Key Helm Commands

helm list -n <ns>                           # List releases
helm history <release> -n <ns>              # Revision history
helm status <release> -n <ns>               # Current status
helm get values <release> -n <ns>           # Active values
helm get manifest <release> -n <ns>         # Rendered manifests
helm template <chart> -f <values> --debug   # Debug rendering
helm rollback <release> <rev> -n <ns>       # Rollback
helm upgrade <release> <chart> -f <values>  # Upgrade
helm lint <chart>                           # Validate chart

See also: - training/library/runbooks/cicd/helm_upgrade_failed.md - training/interactive/runtime-labs/lab-runtime-05-helm-upgrade-rollback/ (local lab, not in wiki) - training/interview-scenarios/05-helm-upgrade-broke-prod.md