Debugging and Troubleshooting

1. Using Debug Mode

Flag	Description	Default
--debug	Enable verbose logging output	false
--dry-run	Simulate installation without making changes	false

Example: Enable debug mode during installation

helm install my-release ./my-chart --debug

Example: Dry run to preview changes

helm install my-release ./my-chart --dry-run

Note: Debug mode logs detailed information about the chart's rendering process, including templates and values.

2. Generating Templates Locally

Command	Description	Options	Example
helm template	Render chart templates locally	`--debug`, `--values`, `--set`	`helm template my-release ./my-chart`
helm lint	Check chart for possible issues	`--strict`, `--set`	`helm lint ./my-chart`

Example: Rendering a Chart Template

helm template my-release ./my-chart --debug

Example: Linting a Chart

helm lint ./my-chart --strict

Note: Use helm template to preview rendered manifests before installing or upgrading.

Warning: helm template does not validate values or check for missing required fields.

3. Performing Dry Run

Example: Helm Dry Run

helm install my-release ./my-chart --dry-run --debug

Option	Values	Description
--dry-run	`true`	Simulate an install without actually installing the chart
--debug	`true`	Enable verbose logging and output of rendered templates

Note: The --dry-run flag does not validate the values provided, it only renders the templates.

Warning: The --dry-run does not check for the existence of resources or permissions.

4. Viewing Rendered Manifests

When debugging Helm charts, it's often useful to see the actual Kubernetes manifests that are generated after rendering. This can help identify issues with templates, values, or chart structure.

Example: Using `helm template`

helm template my-release ./my-chart

Command	Description	Notes
helm template <release-name> <chart-path>	Render chart templates locally	Does not require a Kubernetes cluster
helm template <release-name> <chart-path> --values <values-file>	Render chart with custom values	Useful for debugging specific configurations
helm template <release-name> <chart-path> --debug	Include debug information in output	Shows template execution details

Note: The helm template command is particularly useful for validating chart structure and identifying syntax errors before installing or upgrading a release.

Example: Rendering with debug output

helm template my-release ./my-chart --debug

Example: Rendering with custom values file

helm template my-release ./my-chart --values production-values.yaml

5. Checking Release Status

Command	Description	Notes
helm status <release-name>	Displays the status of the named release	Shows release revision, status, namespace, and chart name
helm status <release-name> -o json	Displays the status in JSON format	Useful for scripting and automation
helm status <release-name> --show-resources	Shows all resources managed by the release	Helps in identifying resource dependencies and status

Example: Checking Release Status

helm status my-app
NAME: my-app
LAST DEPLOYED: Mon Apr 15 10:30:45 2024
NAMESPACE: default
STATUS: deployed
REVISION: 3
DESCRIPTION: Release revision 3

Example: Checking Release Status with Resources

helm status my-app --show-resources
NAME: my-app
LAST DEPLOYED: Mon Apr 15 10:30:45 2024
NAMESPACE: default
STATUS: deployed
REVISION: 3
DESCRIPTION: Release revision 3
RESOURCES:
  <REDACTED>
  <REDACTED>
  <REDACTED>

6. Viewing Release History

Command	Description	Flags
helm history	Lists the history of releases for a specific release	`--max`, `--output`, `--namespace`

Example: View release history

helm history my-release

Example: View release history with max entries

helm history my-release --max 5

Note: The helm history command shows all past versions of a release, including rollbacks and upgrades.

7. Inspecting Hook Execution

Hook Type	Description	Execution Order	Notes
pre-install	Runs before resources are created	1st	Use for validation or setup tasks
post-install	Runs after resources are created	2nd	Use for finalization or logging
pre-upgrade	Runs before upgrade process begins	3rd	Use for backup or pre-checks
post-upgrade	Runs after upgrade completes	4th	Use for cleanup or notifications
pre-delete	Runs before chart is deleted	5th	Use for cleanup or confirmation
post-delete	Runs after chart is deleted	6th	Use for logging or final cleanup
pre-test	Runs before test hooks	7th	Use for setup before tests
post-test	Runs after test hooks	8th	Use for reporting or cleanup

Example: Hook Configuration in values.yaml

hooks:
  - name: pre-install-hook
    type: pre-install
    image: busybox:1.35
    command: [&#34;echo&#34;, &#34;Running pre-install hook&#34;]
    schedule: &#34;0 0 * * *&#34;

Example: Inspecting Hook Logs

helm status my-release
kubectl logs -l release=my-release,job-name=pre-install-hook

Note: Hooks execute in the context of a Kubernetes Job or CronJob, and their logs can be inspected using standard kubectl commands.

Warning: Hooks that fail will cause the overall Helm operation to fail unless marked as failures: ignore.

8. Checking Resource Events

Resource Type	Event Type	Description	Command
Pod	`Normal`	Pod scheduled successfully	`kubectl get events --field-selector involvedObject.kind=Pod`
Deployment	`Warning`	Deployment rollout failed	`kubectl get events --field-selector involvedObject.kind=Deployment`
Service	`Normal`	Service created or updated	`kubectl get events --field-selector involvedObject.kind=Service`
ConfigMap	`Warning`	ConfigMap not found during pod creation	`kubectl get events --field-selector involvedObject.kind=ConfigMap`

Example: Fetching Events for a Specific Pod

kubectl get events --field-selector involvedObject.name=pod-name

Note: Events are time-stamped and can help identify timing issues in resource creation or updates.

9. Validating Current Values

Example: Check current values

helm get values <release-name>

Command	Description	Notes
helm get values	Displays current values for a release	Shows effective values used during chart installation
helm get values -a	Displays all values including defaults	Includes default values not overridden by user

Note: The helm get values command shows the effective values used during chart installation, which may differ from what was explicitly set due to default values or value merging.

10. Using Verbose Output

Flag	Description	Usage
--debug	Enables verbose logging for Helm operations	`helm install --debug my-release ./my-chart`
--dry-run	Simulates the Helm operation without making changes	`helm upgrade --dry-run my-release ./my-chart`
-v, --verbose	Increases verbosity level (1-10)	`helm template -v 5 my-release ./my-chart`

Example: Debugging a failed Helm install

helm install --debug --dry-run my-release ./my-chart

Note: The --debug flag is particularly useful for debugging template rendering issues.

11. Troubleshooting Failed Upgrades

Issue	Description	Solution
Upgrade fails due to incompatible schema changes	Chart version mismatch or schema incompatibility between old and new chart versions.	Ensure the new chart version is compatible or use `--force` to override.
Resource conflicts during upgrade	Resources like Services or ConfigMaps already exist and conflict with new definitions.	Use `--recreate-pods` or manually delete conflicting resources.
Timeout during upgrade	Upgrade process exceeds default timeout (300s) due to large resources or slow network.	Adjust `--timeout` value (e.g., `--timeout 600s`) to allow more time.
Rollback fails after failed upgrade	When `helm rollback` is attempted but fails due to missing resources or chart changes.	Use `helm history` to check revision and manually restore resources if needed.

Example: Upgrade with timeout and force

helm upgrade my-release ./my-chart --timeout 600s --force

Note: Always backup your release before attempting a forced upgrade or rollback.

Warning: Using --force may cause data loss or unexpected behavior in some cases.

Common Upgrade Failure Patterns

Schema Incompatibility: Chart version changes break existing resources.
Resource Conflicts: New resource definitions clash with existing ones.
Timeouts: Long-running upgrades get terminated prematurely.

12. Debugging Template Rendering

Command	Description	Notes
helm template	`helm template <release-name> <chart-path>`	Render templates locally without installing
helm template --debug	`helm template --debug <release-name> <chart-path>`	Enable debug mode to show template execution details

Example: Rendering a Chart with Debug Info

helm template my-release ./my-chart --debug

Note: The --debug flag shows the rendered templates and values used during rendering.

Example: Inspecting Values Used in Template

helm get values my-release

Warning: Template rendering errors may not show full context in debug mode. Use helm template with verbose logging for better diagnostics.