helm-debugging

Helm のデバッグとトラブルシューティング

Helm のデプロイ失敗、テンプレートエラー、設定の問題を診断して修正するための包括的なガイダンスです。

このスキルを使用するタイミング

次の場合はこのスキルを使用してください…	次の場合は代わりにを使用してください…
テンプレートのレンダリングエラー、値の型エラー、YAML の解析エラーを診断する場合	リリース自体が停止（pending-install/upgrade）しており、ロールバックが必要な場合は helm-release-recovery を使用してください
チャートのデプロイ後にポッドがクラッシュする、またはイメージをプルできない原因を調査する場合	エフェメラルコンテナまたはノードレベルのデバッグセッションが必要な場合は kubectl-debugging を使用してください
デプロイ前の検証に helm lint、helm template、または --dry-run を実行する場合	チャートをゼロから作成または再構成する場合は helm-chart-development を使用してください

使用するタイミング

次の場合は、このスキルを自動的に使用してください。

• ユーザーから Helm のデプロイ失敗やエラーが報告された
• ユーザーが Helm の問題のデバッグ、トラブルシューティング、修正について言及した
• テンプレートのレンダリングに問題が発生した
• 値の検証または型エラーが発生した
• リソースの競合または API エラーが発生した
• イメージのプル失敗またはポッドのクラッシュが発生した
• ユーザーがデプロイ済みリソースの調査を必要としている

コンテキストの安全性（重要）

kubectl コマンドと helm コマンドでは、必ず明示的に --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?

これにより、誤ったクラスターに対する操作を防げます。

---

段階的な検証方法

堅牢なデプロイを実現するため、必ず次の順序に従ってください。

# 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

基本的なデバッグコマンド

テンプレートのレンダリングと調査

# 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

デプロイ済みリソースの調査

# 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

チャートの検証

# 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

詳細なデバッグ

# 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

よくある失敗のシナリオ

シナリオ	症状	すぐにできる対処
YAML 解析エラー	error converting YAML to JSON	インデントを確認し、空白を削除するには {{- ... }} を使用します
テンプレートのレンダリングエラー	nil pointer evaluating interface	デフォルト値を追加します：{{ .Values.key | default "value" }}
値の型エラー	cannot unmarshal string into Go value of type int	テンプレートで {{ .Values.port | int }} を使用します
リソースがすでに存在する	resource that already exists	競合するリリースを helm uninstall でアンインストールするか、リソースを引き継ぎます
イメージのプル失敗	ImagePullBackOff	イメージ名またはタグを修正し、プルシークレットを作成します
CRD が見つからない	no matches for kind	先に CRD をインストールします：kubectl apply -f crds/
タイムアウト	timed out waiting for the condition	--timeout を延長し、レディネスプローブを確認します
フックの失敗	pre-upgrade hooks failed	失敗したフックジョブを削除し、--no-hooks を指定して再試行します

各失敗シナリオの詳細なデバッグ手順、修正方法、例については、REFERENCE.md を参照してください。

エージェント向けの最適化

コンテキスト	コマンド
リリースのステータス（JSON）	helm status <release> -n <ns> -o json
すべての値（JSON）	helm get values <release> -n <ns> --all -o json
ポッドのステータス（コンパクト）	kubectl get pods -n <ns> -l app.kubernetes.io/instance=<release> -o wide
イベント（ソート済み）	kubectl get events -n <ns> --sort-by='.lastTimestamp' -o json
レンダリングと検証	helm template <release> ./chart --debug 2>&1 | head -100

関連スキル

• Helm リリース管理 - インストール、アップグレード、アンインストール操作
• Helm 値の管理 - 高度な設定管理
• Helm リリースの復旧 - ロールバックと復旧の方法
• Kubernetes の操作 - K8s リソースの管理とデバッグ
• ArgoCD CLI ログイン - ArgoCD を使用した GitOps のデバッグ

参考資料

• Helm デバッグドキュメント
• Helm トラブルシューティングガイド
• Kubernetes のデバッグ
• テンプレート関数リファレンス