Debugging and Troubleshooting
1. Using Debug Mode
| Flag | Effect |
|---|
--debug | Verbose output including computed values + stack traces |
2. Generating Templates Locally
Example: Render to file
helm template api ./chart -f values-prod.yaml > rendered.yaml
| Type | Difference |
|---|
--dry-run=client | Local render only |
--dry-run=server | Sends to API server (admission webhooks run) |
4. Viewing Rendered Manifests
| Command | Output |
|---|
helm get manifest <release> | What's currently installed |
helm template ... | What would be installed |
diff <(helm get manifest x) <(helm template x ./chart) | Manual diff |
5. Checking Release Status
Example: Detailed status
helm status api -n web --show-resources --show-desc
6. Viewing Release History
| Command | Use |
|---|
helm history api | List revisions |
helm get all api --revision 3 | Inspect older revision |
7. Inspecting Hook Execution
Example: View hook pods/jobs
kubectl get pods -n web -l owner=helm
helm get hooks api
8. Checking Resource Events
| Command | Use |
|---|
kubectl describe pod <name> | Events at end of output |
kubectl get events -n web --sort-by=.lastTimestamp | Recent cluster events |
9. Validating Current Values
Example: Diff values vs file
helm get values api -o yaml > current.yaml
diff current.yaml values-prod.yaml
10. Using Verbose Output
| Flag | Effect |
|---|
-v=4 ... -v=9 | Kubernetes client log verbosity |
HELM_DEBUG=true | Permanent debug mode |
11. Troubleshooting Failed Upgrades
| Symptom | Resolution |
|---|
Stuck pending-upgrade | Patch release secret status to deployed, then re-run |
| Immutable field changes | Use --force or delete + reinstall single resource |
| Quota exceeded | Increase namespace quota or scale down replicas first |
| Image pull error | Check pull secret, registry credentials |
| Webhook failure | Check admission controllers (OPA/Kyverno/cert-manager) |
12. Debugging Template Rendering
Example: Pinpoint failure
helm template ./chart --debug 2>&1 | less
helm template ./chart --show-only templates/deployment.yaml
Note: The helm-diff plugin provides clean upgrade previews: helm diff upgrade api ./chart -f values.yaml.