k8s-troubleshooter

Kubernetes のトラブルシューティングとインシデント対応

本番環境における Kubernetes の問題を診断し、解決するための体系的なアプローチです。

基本的なトラブルシューティングのワークフロー

Kubernetes の問題には、次の体系的なアプローチで対応します。

1. コンテキストを収集する

• 観測されている症状は何ですか？
• いつ発生し始めましたか？
• 最近、何が変更されましたか（デプロイ、設定、インフラストラクチャ）？
• 影響範囲はどこですか（単一の Pod、サービス、ノード、クラスター）？
• ビジネスへの影響はどの程度ですか（重大度レベル）？

2. 初期トリアージ

クラスターのヘルスチェックを実行します。

# Check node status and health
kubectl get nodes

# Find non-running pods across all namespaces
kubectl get pods -A --field-selector status.phase!=Running

# Check node resource usage
kubectl top nodes

次の概要を確認できます。

• ノードのヘルスステータス
• すべての名前空間における保留中および失敗した Pod
• ノードのリソース使用状況

3. 詳細な調査

トリアージの結果に基づいて調査対象を絞り込みます。

名前空間レベルの問題の場合：

python3 scripts/check_namespace.py <namespace>

名前空間のヘルス状態を包括的に確認できます。

• Pod のステータス（実行中、保留中、失敗、クラッシュループ中）
• サービスのヘルス状態とエンドポイント
• Deployment の可用性
• PVC のステータス
• リソースクォータの使用状況
• 最近のイベント
• 実行可能な推奨事項

Pod の問題の場合：

# Get full pod details (status, events, conditions, resource config)
kubectl describe pod <pod-name> -n <namespace>

# Check current and previous container logs
kubectl logs <pod-name> -n <namespace>
kubectl logs <pod-name> -n <namespace> --previous

# Get events specific to the pod
kubectl get events -n <namespace> --field-selector involvedObject.name=<pod-name>

次の情報を確認できます。

• Pod のフェーズと準備状態
• コンテナーのステータスと状態
• 再起動回数と終了コード
• 最近のイベントとスケジューリングの判断
• リソース要求と制限

追加の調査：

• すべての名前空間のイベントを確認します：kubectl get events -n <namespace> --sort-by='.lastTimestamp'

4. 根本原因を特定する

references/common_issues.md で、次の問題に関する詳細を確認します。

• ImagePullBackOff / ErrImagePull
• CrashLoopBackOff
• Pending Pods
• OOMKilled
• ノードの問題（NotReady、DiskPressure）
• ネットワーク障害
• ストレージ／PVC の問題
• リソースクォータとスロットリング
• RBAC 権限エラー

各問題には、次の情報が含まれています。

• 症状
• 一般的な原因
• 診断コマンド
• 修復手順
• 予防策

5. 修復を適用する

特定した根本原因に基づいて、common_issues.md の修復手順に従います。

必ず次のことを行います。

• 可能であれば、まず本番環境以外で修正をテストします
• 実施した対応を記録します
• 効果を監視します
• ロールバック計画を用意しておきます

6. 検証と監視

修正を適用した後、次のことを行います。

• 問題が解決したことを確認します
• 再発がないか監視します（最低 15～30 分）
• 関連するシステムを確認します
• ドキュメントを更新します

インシデント対応

本番環境のインシデントには、references/incident_response.md の体系的な対応手順に従います。

重大度の評価：

• SEV-1（重大）：完全な停止、データ損失、セキュリティ侵害
• SEV-2（高）：大幅な性能低下、ユーザーへの重大な影響
• SEV-3（中）：軽微な障害、回避策あり
• SEV-4（低）：外観上の問題、影響は最小限

インシデントのフェーズ：

1. 検出 - 特定して評価する
2. トリアージ - 範囲と影響を判断する
3. 調査 - 根本原因を見つける
4. 解決 - 修正を適用する
5. インシデント後 - 記録して改善する

一般的なインシデントのシナリオ：

• クラスターの完全な停止
• サービスの性能低下
• ノード障害
• ストレージの問題
• セキュリティインシデント

詳細な対応手順については、references/incident_response.md を参照してください。

クイックリファレンスコマンド

クラスターの概要

kubectl cluster-info
kubectl get nodes
kubectl get pods --all-namespaces | grep -v Running
kubectl get events --all-namespaces --sort-by='.lastTimestamp' | tail -20

Pod の診断

kubectl describe pod <pod> -n <namespace>
kubectl logs <pod> -n <namespace>
kubectl logs <pod> -n <namespace> --previous
kubectl exec -it <pod> -n <namespace> -- /bin/sh
kubectl get pod <pod> -n <namespace> -o yaml

ノードの診断

kubectl describe node <node>
kubectl top nodes
kubectl top pods --all-namespaces
ssh <node> "systemctl status kubelet"
ssh <node> "journalctl -u kubelet -n 100"

サービスとネットワーク

kubectl describe svc <service> -n <namespace>
kubectl get endpoints <service> -n <namespace>
kubectl get networkpolicies --all-namespaces

ストレージ

kubectl get pvc,pv --all-namespaces
kubectl describe pvc <pvc> -n <namespace>
kubectl get storageclass

リソースと設定

kubectl describe resourcequota -n <namespace>
kubectl describe limitrange -n <namespace>
kubectl get rolebindings,clusterrolebindings -n <namespace>

診断スクリプト

check_namespace.py

名前空間レベルのヘルスチェックと診断：

• Pod のヘルス状態（実行中、保留中、失敗、クラッシュループ中、イメージのプルエラー）
• サービスのヘルス状態とエンドポイント
• Deployment の可用性ステータス
• PersistentVolumeClaim のステータス
• リソースクォータの使用状況と制限
• 最近の名前空間イベント
• ヘルスステータスの評価
• 実行可能な推奨事項

使用方法：

# Human-readable output
python3 scripts/check_namespace.py <namespace>

# JSON output for automation
python3 scripts/check_namespace.py <namespace> --json

# Include more events
python3 scripts/check_namespace.py <namespace> --events 20

特定の名前空間における問題のトラブルシューティングや、名前空間全体のヘルス状態の評価に適しています。

クラスター全体の診断（kubectl）

クラスター全体のヘルスチェックには、kubectl を直接使用します。

# Node health and status
kubectl get nodes
kubectl top nodes

# Find non-running pods across all namespaces
kubectl get pods -A --field-selector status.phase!=Running

# System pod health
kubectl get pods -n kube-system

Pod レベルの診断（kubectl）

Pod の詳細な調査には、kubectl を直接使用します。

# Full pod details (status, events, conditions, resource config)
kubectl describe pod <pod-name> -n <namespace>

# Current and previous container logs
kubectl logs <pod-name> -n <namespace>
kubectl logs <pod-name> -n <namespace> --previous

# Events specific to the pod
kubectl get events -n <namespace> --field-selector involvedObject.name=<pod-name>

リファレンスドキュメント

references/common_issues.md

以下を含む、Kubernetes の一般的な問題に関する包括的なガイドです。

• 症状の詳細な説明
• 根本原因の分析
• 段階的な診断手順
• 修正手順
• 予防策

対象：

• Pod の問題（ImagePullBackOff、CrashLoopBackOff、Pending、OOMKilled）
• ノードの問題（NotReady、DiskPressure）
• ネットワークの問題（Pod 間通信、サービスへのアクセス）
• ストレージの問題（PVC が Pending のままになる、ボリュームのマウント失敗）
• リソースの問題（クォータ超過、CPU スロットリング）
• セキュリティの問題（脆弱性、RBAC）

特定の問題の種類を特定したものの、詳細な修正手順が必要な場合にお読みください。

references/incident_response.md

以下を含む、体系化されたインシデント対応フレームワークです。

• インシデント対応のフェーズ（検知 → トリアージ → 調査 → 解決 → インシデント後）
• 重大度レベルの定義
• 一般的なインシデントシナリオに対する詳細なプレイブック
• コミュニケーションのガイドライン
• インシデント後レビューのテンプレート
• 予防、準備、対応、復旧のベストプラクティス

本番環境のインシデントへの対応時や、インシデント対応手順を計画する際にお読みください。

references/performance_troubleshooting.md

以下を網羅する、包括的なパフォーマンス診断・最適化ガイドです。

• 高レイテンシの問題 - API 応答時間、リクエストレイテンシのトラブルシューティング
• CPU パフォーマンス - スロットリングの検出、プロファイリング、最適化
• メモリパフォーマンス - OOM の問題、リークの検出、ヒーププロファイリング
• ネットワークパフォーマンス - レイテンシ、パケット損失、DNS 解決
• ストレージ I/O パフォーマンス - ディスクパフォーマンスのテスト、最適化
• アプリケーションレベルのメトリクス - Prometheus の統合、分散トレーシング
• クラスター全体のパフォーマンス - コントロールプレーン、スケジューラー、リソース使用率

以下の場合にお読みください。

• アプリケーションの応答時間が遅い原因を調査する場合
• CPU またはメモリのパフォーマンスの問題を診断する場合
• ネットワークのレイテンシや接続の問題をトラブルシューティングする場合
• ストレージ I/O パフォーマンスを最適化する場合
• パフォーマンス監視を設定する場合

references/helm_troubleshooting.md

以下を含む、Helm のトラブルシューティングに関する包括的なガイドです。

• リリースの問題 - リリースの停止、リソースの欠落、状態の問題
• インストールの失敗 - チャートの競合、検証エラー、テンプレートのレンダリング
• アップグレードとロールバック - アップグレードの失敗、不変フィールドのエラー、ロールバック手順
• 値と設定 - 値が適用されない、解析エラー、シークレットの処理
• チャートの依存関係 - 依存関係の更新、バージョンの競合、サブチャートの値
• フックとライフサイクル - フックの失敗、クリーンアップの問題
• リポジトリの問題 - チャートへのアクセスの問題、バージョンの不一致

以下の場合にお読みください。

• Helm でデプロイされたアプリケーションを扱う場合
• チャートのインストールやアップグレードをトラブルシューティングする場合
• Helm リリースの状態をデバッグする場合
• チャートの依存関係を管理する場合