In this lesson, you will learn how to bypass the trial-and-error cycle of deploying to a cluster by using local diagnostic tools to visualize your rendered Helm manifests.
When you work with deeply nested subcharts, global values, and complex Go template logic, it is easy for a missing variable or an incorrect indentation to break your deployment. Instead of applying changes directly to your cluster, you should leverage the built-in "dry-run" capabilities to catch rendering errors early.
Using --dry-run and --debug
The most effective way to troubleshoot a template is to run:
helm install <release-name> <chart-path> --dry-run --debug
The --dry-run flag instructs Helm to process the templates without actually communicating with the Kubernetes API server. Adding --debug is the crucial step; it prints the fully rendered manifests to your console. This allows you to inspect exactly how your logic—such as range loops or if-else blocks—resolved the final configuration. If a block of YAML is missing or misconfigured, you can spot it immediately in the output.
Inspecting with helm template
If you prefer a cleaner output without the installation overhead, use the helm template command:
helm template <release-name> <chart-path> --values values.yaml --show-only templates/deployment.yaml
The --show-only flag is a lifesaver when dealing with complex charts containing dozens of files. It filters the output, letting you focus exclusively on the specific resource you are debugging. This allows for rapid iteration: change a line of logic in your template, rerun the command, and observe the immediate change in the output.
Advanced Introspection
For complex logic involving pipelines, you can use the print function inside your template to debug values at runtime:
{{- printf "DEBUG: The value of myVar is %s" .Values.myVar | fail -}}
By injecting a fail function triggered by a print statement, you force Helm to stop rendering and display the value of a specific variable in your terminal, providing a "print-debugging" mechanism for your templates.
Key Takeaway: Never deploy untested templates; use helm template --debug or helm install --dry-run to inspect the final rendered YAML and catch logic errors before they ever reach your cluster.