skillZs
★ LIVE SKILL TAGS ★
>>> LIVE SKILLS INDEX <<<
* OPEN SOURCE *
NO LOGIN, NO TRACKING
※ REAL INSTALL DATA ※
← back to all skills
laurigates/claude-plugins81 installs

helm-debugging

Debug Helm failures — template errors, dry-run, YAML parse errors, value type errors, resource conflicts. Use when the user mentions Helm errors or template rendering issues.

How do I install this agent skill?

npx skills add https://github.com/laurigates/claude-plugins --skill helm-debugging
view source ↗

Is this agent skill safe to install?

  • Gen Agent Trust Hubpass

    The skill provides standard debugging procedures for Helm and Kubernetes deployments. It emphasizes context safety and validation steps. The primary security consideration is the potential for indirect prompt injection when the agent reads application logs or cluster events, which are untrusted data sources.

  • Socketpass

    No alerts

  • Snykpass

    Risk: LOW · No issues

  • Runlayerwarn

    2/2 files flagged

What does this agent skill do?

Helm Debugging & Troubleshooting

Comprehensive guidance for diagnosing and fixing Helm deployment failures, template errors, and configuration issues.

When to Use This Skill

Use this skill when...Use <sibling> instead when...
Diagnosing template render errors, value type errors, or YAML parse failuresUse helm-release-recovery when the release itself is stuck (pending-install/upgrade) and needs rollback
Inspecting why a chart deployed but pods are crashing or images won't pullUse kubectl-debugging when you need an ephemeral container or node-level debug session
Running helm lint, helm template, or --dry-run to validate before deployUse helm-chart-development when authoring or restructuring a chart from scratch

When to Use

Use this skill automatically when:

  • User reports Helm deployment failures or errors
  • User mentions debugging, troubleshooting, or fixing Helm issues
  • Template rendering problems occur
  • Value validation or type errors
  • Resource conflicts or API errors
  • Image pull failures or pod crashes
  • User needs to inspect deployed resources

Context Safety (CRITICAL)

Always specify --context explicitly in all kubectl and helm commands. Never rely on the current context.

# CORRECT: Explicit context
kubectl --context=prod-cluster get pods -n prod
helm --kube-context=prod-cluster status myapp -n prod

# WRONG: Relying on current context
kubectl get pods -n prod  # Which cluster?

This prevents accidental operations on the wrong cluster.


Layered Validation Approach

ALWAYS follow this progression for robust deployments:

# 1. LINT - Static analysis (local charts only)
helm lint ./mychart --strict

# 2. TEMPLATE - Render templates locally
helm template myapp ./mychart \
  --debug \
  --values values.yaml

# 3. DRY-RUN - Server-side validation
helm install myapp ./mychart \
  --namespace prod \
  --values values.yaml \
  --dry-run --debug

# 4. INSTALL - Actual deployment
helm install myapp ./mychart \
  --namespace prod \
  --values values.yaml \
  --atomic --wait

# 5. TEST - Post-deployment validation (if chart has tests)
helm test myapp --namespace prod --logs

Core Debugging Commands

Template Rendering & Inspection

# Render all templates locally
helm template myapp ./mychart \
  --debug \
  --values values.yaml

# Render specific template file
helm template myapp ./mychart \
  --show-only templates/deployment.yaml \
  --values values.yaml

# Render with debug output (shows computed values)
helm template myapp ./mychart \
  --debug \
  --values values.yaml \
  2>&1 | less

# Validate against Kubernetes API (dry-run)
helm install myapp ./mychart \
  --namespace prod \
  --values values.yaml \
  --dry-run \
  --debug

Inspect Deployed Resources

# Get deployed manifest (actual YAML in cluster)
helm get manifest myapp --namespace prod

# Get deployed values (what was actually used)
helm get values myapp --namespace prod

# Get ALL values (including defaults)
helm get values myapp --namespace prod --all

# Get release status with resources
helm status myapp --namespace prod --show-resources

# Get everything about a release
helm get all myapp --namespace prod

Chart Validation

# Lint chart structure and templates
helm lint ./mychart

# Lint with strict mode (treats warnings as errors)
helm lint ./mychart --strict

# Lint with specific values
helm lint ./mychart --values values.yaml --strict

# Validate chart against Kubernetes API
helm install myapp ./mychart \
  --dry-run --validate --namespace prod

Verbose Debugging

# Enable Helm debug logging
helm install myapp ./mychart \
  --namespace prod \
  --debug \
  --dry-run

# Enable Kubernetes client logging
helm install myapp ./mychart \
  --namespace prod \
  --v=6  # Verbosity level 0-9

Common Failure Scenarios

ScenarioSymptomQuick Fix
YAML parse errorerror converting YAML to JSONCheck indentation, use {{- ... }} for whitespace chomping
Template rendering errornil pointer evaluating interfaceAdd defaults: {{ .Values.key | default "value" }}
Value type errorcannot unmarshal string into Go value of type intUse {{ .Values.port | int }} in template
Resource already existsresource that already existshelm uninstall conflicting release or adopt resource
Image pull failureImagePullBackOffFix image name/tag, create pull secret
CRD not foundno matches for kindInstall CRDs first: kubectl apply -f crds/
Timeouttimed out waiting for the conditionIncrease --timeout, check readiness probes
Hook failurepre-upgrade hooks failedDelete failed hook job, retry with --no-hooks

For detailed debugging steps, fixes, and examples for each failure scenario, see REFERENCE.md.

Agentic Optimizations

ContextCommand
Release status (JSON)helm status <release> -n <ns> -o json
All values (JSON)helm get values <release> -n <ns> --all -o json
Pod status (compact)kubectl get pods -n <ns> -l app.kubernetes.io/instance=<release> -o wide
Events (sorted)kubectl get events -n <ns> --sort-by='.lastTimestamp' -o json
Render + validatehelm template <release> ./chart --debug 2>&1 | head -100

Related Skills

  • Helm Release Management - Install, upgrade, uninstall operations
  • Helm Values Management - Advanced configuration management
  • Helm Release Recovery - Rollback and recovery strategies
  • Kubernetes Operations - Managing and debugging K8s resources
  • ArgoCD CLI Login - GitOps debugging with ArgoCD

References

Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.

<a href="https://skillzs.dev/skills/laurigates/claude-plugins/helm-debugging">View helm-debugging on skillZs</a>