helm-release-recovery

Helm リリースの復旧

Helm デプロイの失敗からの復旧、リリースのロールバック、停止中または破損したリリース状態の管理に関する包括的なガイダンスです。

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

次の場合にこのスキルを使用します...	次の場合は代わりにを使用します...
失敗した helm upgrade をロールバックする、または以前のリビジョンに戻す	問題が発生していない通常のインストール／アップグレード／アンインストールには、helm-release-managementを使用します
停止中の pending-install または pending-upgrade 状態を解除する	根本原因がテンプレート、値、またはレンダリングされたマニフェストにある場合は、helm-debuggingを使用します
破損したリリースシークレットや不完全なデプロイをクリーンアップする	復旧のために個々のポッドやノードの確認が必要な場合は、kubectl-debuggingを使用します

使用するタイミング

次の場合は、このスキルを自動的に使用します。

• ユーザーが失敗または問題のあるデプロイのロールバックを必要としている
• ユーザーが停止中のリリース（pending-install、pending-upgrade）を報告している
• ユーザーがアップグレードの失敗または不完全なデプロイについて言及している
• ユーザーが破損したリリース状態からの復旧を必要としている
• ユーザーがリリース履歴を表示したい
• ユーザーが失敗したリリースのクリーンアップを必要としている

主な復旧操作

以前のリビジョンにロールバックする

# Rollback to previous revision (most recent successful)
helm rollback <release> --namespace <namespace>

# Rollback to specific revision number
helm rollback <release> 3 --namespace <namespace>

# Rollback with wait and atomic behavior
helm rollback <release> \
  --namespace <namespace> \
  --wait \
  --timeout 5m \
  --cleanup-on-fail

# Rollback without waiting (faster but less safe)
helm rollback <release> \
  --namespace <namespace> \
  --no-hooks

主なフラグ：

• --wait - リソースの準備が完了するまで待機します
• --timeout - 待機する最大時間（デフォルトは5m）
• --cleanup-on-fail - ロールバックに失敗した場合、新しいリソースを削除します
• --no-hooks - ロールバックフックの実行をスキップします
• --force - 削除／再作成によってリソースの更新を強制します
• --recreate-pods - 該当する場合、リソースのポッドを再起動します

リリース履歴を表示する

# View all revisions
helm history <release> --namespace <namespace>

# View detailed history (YAML format)
helm history <release> \
  --namespace <namespace> \
  --output yaml

# Limit number of revisions shown
helm history <release> \
  --namespace <namespace> \
  --max 10

履歴の出力フィールド：

• REVISION：連番のバージョン番号
• UPDATED：デプロイのタイムスタンプ
• STATUS：deployed、superseded、failed、pending-install、pending-upgrade
• CHART：チャート名とバージョン
• APP VERSION：アプリケーションのバージョン
• DESCRIPTION：発生した内容（インストール完了、アップグレード完了、X へのロールバック）

リリースのステータスを確認する

# Check current release status
helm status <release> --namespace <namespace>

# Show deployed resources
helm status <release> \
  --namespace <namespace> \
  --show-resources

# Get status of specific revision
helm status <release> \
  --namespace <namespace> \
  --revision 5

よくある復旧シナリオ

シナリオ 1：直近のデプロイに失敗した場合 — シンプルなロールバック

症状：

• 直近のアップグレード／インストールに失敗した
• デプロイ後にアプリケーションが動作しない
• 以前の正常に動作していたバージョンに戻したい

復旧手順：

# 1. Check release status
helm status myapp --namespace production

# 2. View history to identify good revision
helm history myapp --namespace production

# Output example:
# REVISION  STATUS      CHART        DESCRIPTION
# 1         superseded  myapp-1.0.0  Install complete
# 2         superseded  myapp-1.1.0  Upgrade complete
# 3         deployed    myapp-1.2.0  Upgrade "myapp" failed

# 3. Rollback to previous working revision (2)
helm rollback myapp 2 \
  --namespace production \
  --wait \
  --timeout 5m

# 4. Verify rollback
helm history myapp --namespace production

# 5. Verify application health
kubectl get pods -n production -l app.kubernetes.io/instance=myapp
helm status myapp --namespace production

シナリオ 2：リリースが停止中（pending-install/pending-upgrade）

症状：

helm list -n production
# NAME   STATUS          CHART
# myapp  pending-upgrade myapp-1.0.0

復旧手順：

# 1. Check what's actually deployed
kubectl get all -n production -l app.kubernetes.io/instance=myapp

# 2. Check release history
helm history myapp --namespace production

# Option A: Rollback to previous working revision
helm rollback myapp <previous-working-revision> \
  --namespace production \
  --wait

# Option B: Force new upgrade to unstick
helm upgrade myapp ./chart \
  --namespace production \
  --force \
  --wait \
  --atomic

# Option C: If rollback fails, delete and reinstall
# WARNING: This will cause downtime
helm uninstall myapp --namespace production --keep-history
helm install myapp ./chart --namespace production --atomic

# 3. Verify recovery
helm status myapp --namespace production

不完全なデプロイ、破損した履歴、ロールバックの失敗、連鎖障害などの追加の復旧シナリオ、履歴の管理、アトミックなデプロイパターン、復旧のベストプラクティス、トラブルシューティング、CI/CD との連携については、REFERENCE.mdを参照してください。

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

コンテキスト	コマンド
リリース履歴（JSON）	helm history <release> -n <ns> --output json
リリースのステータス（JSON）	helm status <release> -n <ns> -o json
リビジョンの値（JSON）	helm get values <release> -n <ns> --revision <N> -o json
ポッドのステータス（簡潔な表示）	kubectl get pods -n <ns> -l app.kubernetes.io/instance=<release> -o wide
Helm シークレット（一覧）	kubectl get secrets -n <ns> -l owner=helm,name=<release> -o json

関連スキル

• Helm リリース管理 - インストール、アップグレード操作
• Helm デバッグ - デプロイ失敗のトラブルシューティング
• Helm 値の管理 - 設定の管理
• Kubernetes 操作 - デプロイ済みリソースの管理

参考資料

• Helm ロールバックのドキュメント
• Helm リリース管理
• Helm 履歴のドキュメント
• Helm ストレージバックエンド