k8s-debug

Kubernetes のデバッグスキル

概要

Kubernetes クラスター、ワークロード、ネットワーク、ストレージを、安全性を優先した決定論的なワークフローで体系的にデバッグするためのツールキットです。

トリガーフレーズ

次のようなリクエストでは、このスキルを使用します。

• 「Pod が CrashLoopBackOff になっています。根本原因を特定してください。」
• 「ある Pod では Service の DNS が機能しますが、別の Pod では機能しません。」
• 「Deployment のロールアウトが止まっています。」
• 「Pod が Pending のままで、スケジュールされません。」
• 「変更後、クラスターの健全性が低下したようです。」
• 「PVC が Pending で、Pod がストレージをマウントできません。」

前提条件

相対スクリプトパスを記述どおりに機能させるため、スキルディレクトリ（devops-skills-plugin/skills/k8s-debug）から実行してください。

必須

• kubectl がインストールされ、設定されていること。
• アクティブなクラスターコンテキストがあること。
• Namespace、Pod、イベント、Service、Node に対する読み取りアクセス権があること。

実行前の簡易チェック：

kubectl config current-context
kubectl auth can-i get pods -A
kubectl auth can-i get events -A
kubectl get ns

任意ですが推奨

• ./scripts/cluster_health.sh でより正確にフィルタリングするための jq。
• kubectl top 用の Metrics API（metrics-server）。
• 詳細なネットワークテスト用のコンテナー内デバッグツール（nslookup、getent、curl、wget、ip）。

フォールバック動作：

• 任意のツールがない場合、スクリプトは処理を続け、出力を減らして警告を表示します。
• kubectl top を利用できない場合は、kubectl describe とイベントを使って処理を続けます。

このスキルを使う場面

次の問題には、このスキルを使用します。

• Pod の障害（CrashLoopBackOff、ImagePullBackOff、Pending、OOMKilled）
• Service の接続性または DNS 解決の問題
• ネットワークポリシーまたは Ingress の問題
• ボリュームおよびストレージのマウント障害
• Deployment のロールアウトの問題
• クラスターの健全性またはパフォーマンスの低下
• リソースの枯渇（CPU／メモリ）
• 設定の問題（ConfigMaps、Secrets、RBAC）

破壊的なコマンドに関する安全ルール

デフォルトでは、まず読み取り専用の診断を行います。影響範囲とロールバックを確認してから、破壊的なコマンドを実行してください。

明示的な確認が必要なコマンド：

• kubectl delete pod ... --force --grace-period=0
• kubectl drain ...
• kubectl rollout restart ...
• kubectl rollout undo ...
• kubectl debug ... --copy-to=...

破壊的な操作を行う前に：

# Snapshot current state for rollback and incident notes
kubectl get deploy,rs,pod,svc -n <namespace> -o wide
kubectl get pod <pod-name> -n <namespace> -o yaml > before-<pod-name>.yaml
kubectl get events -n <namespace> --sort-by='.lastTimestamp' > before-events.txt

リファレンスのナビゲーションマップ

確認された症状に必要なセクションだけを読み込みます。

症状／必要な情報	開くファイル	開始セクション
エンドツーエンドの診断手順が必要	./references/troubleshooting_workflow.md	General Debugging Workflow
Pod の状態が Pending、CrashLoopBackOff、または ImagePullBackOff	./references/troubleshooting_workflow.md	Pod Lifecycle Troubleshooting
Service への到達性または DNS の障害	./references/troubleshooting_workflow.md	Network Troubleshooting Workflow
Node の負荷またはパフォーマンスの悪化	./references/troubleshooting_workflow.md	Resource and Performance Workflow
PVC／PV／ストレージクラスの問題	./references/troubleshooting_workflow.md	Storage Troubleshooting Workflow
症状から修正方法をすばやく検索	./references/common_issues.md	該当する問題の見出し
既知の問題に対する事後分析での修正方法	./references/common_issues.md	Solutions セクション

スクリプトの概要

スクリプト	目的	必須引数	任意引数	出力	フォールバック動作
./scripts/cluster_health.sh	クラスター全体のヘルススナップショット（ノード、ワークロード、イベント、よくある障害状態）	なし	--strict、K8S_REQUEST_TIMEOUT 環境変数	標準出力へのセクション別レポート	チェックが失敗しても続行し、サマリーと終了コードに記録します
./scripts/network_debug.sh	Pod を中心としたネットワークおよび DNS の診断	<pod-name>（<namespace> の既定値は default）	--strict、--insecure、K8S_REQUEST_TIMEOUT 環境変数	標準出力へのセクション別レポート	既定ではセキュアな API プローブを使用します。安全でない TLS を使用するには、明示的に --insecure を指定する必要があります
./scripts/pod_diagnostics.py	Pod の詳細な診断（ステータス、describe、YAML、イベント、コンテナごとのログ、ノードのコンテキスト）	<pod-name>	-n/--namespace、-o/--output	標準出力またはファイルへのセクション別レポート	アクセスできない場合は速やかに終了し、任意のメトリクス／ログブロックは明確なメッセージを表示してスキップします

スクリプトの終了コード

./scripts/cluster_health.sh と ./scripts/network_debug.sh は、同じ仕様に従います。

• 0：チェックが失敗せずに完了しました（--strict が設定されていない限り、警告は許容されます）。
• 1：1 つ以上のチェックが失敗した場合、または --strict モードで警告が発生した場合。
• 2：事前条件が満たされず処理がブロックされた場合（例：kubectl がない、有効なコンテキストがない、名前空間／Pod にアクセスできない）。

決定論的なデバッグワークフロー

Kubernetes の問題には、次の体系的な方法で対応してください。

1. 事前確認と範囲の特定

kubectl config current-context
kubectl get ns
kubectl auth can-i get pods -n <namespace>

事前確認に失敗した場合は、いったん停止し、まずアクセス／コンテキストを修正してください。

2. 問題のレイヤーを特定する

問題を分類します。

• アプリケーションレイヤー：アプリケーションのクラッシュ、エラー、バグ
• Pod レイヤー：Pod が起動しない、再起動する、または保留状態になる
• サービスレイヤー：ネットワーク接続、DNS の問題
• ノードレイヤー：ノードが Ready でない、リソースの枯渇
• クラスター レイヤー：コントロールプレーンの問題、API の問題
• ストレージレイヤー：ボリュームのマウント失敗、PVC の問題
• 構成レイヤー：ConfigMap、Secret、RBAC の問題

3. 適切なスクリプトで診断情報を収集する

範囲に応じて、適切な診断スクリプトを使用します。

Pod レベルの診断

Pod を包括的に分析するには、./scripts/pod_diagnostics.py を使用します。

python3 ./scripts/pod_diagnostics.py <pod-name> -n <namespace>

このスクリプトでは、次の情報を収集します。

• Pod のステータスと説明
• Pod のイベント
• コンテナのログ（現在および前回）
• リソース使用量
• ノード情報
• YAML 構成

分析用に出力を保存できます。

python3 ./scripts/pod_diagnostics.py <pod-name> -n <namespace> -o diagnostics.txt

クラスター レベルのヘルスチェック

クラスター全体の診断には、./scripts/cluster_health.sh を使用します。

./scripts/cluster_health.sh > cluster-health-$(date +%Y%m%d-%H%M%S).txt

このスクリプトでは、次の項目をチェックします。

• クラスター情報とバージョン
• ノードのステータスとリソース
• すべての名前空間の Pod
• 失敗／保留状態の Pod
• 最近のイベント
• Deployment、Service、StatefulSet、DaemonSet
• PVC と PV
• コンポーネントのヘルス
• よくあるエラー状態（CrashLoopBackOff、ImagePullBackOff）

ネットワーク診断

接続の問題には、./scripts/network_debug.sh を使用します。

./scripts/network_debug.sh <namespace> <pod-name>
# or force warning sensitivity / insecure TLS only when explicitly needed:
./scripts/network_debug.sh --strict <namespace> <pod-name>
./scripts/network_debug.sh --insecure <namespace> <pod-name>

このスクリプトでは、次の項目を分析します。

• Pod のネットワーク構成
• DNS の設定と名前解決
• サービスのエンドポイント
• ネットワークポリシー
• 接続テスト
• CoreDNS のログ

4. 問題に応じた参照ワークフローに従う

特定した問題に基づいて、./references/troubleshooting_workflow.md を参照します。

• Pod Pending：リソース／スケジューリングのワークフロー
• CrashLoopBackOff：アプリケーションのクラッシュに関するワークフロー
• ImagePullBackOff：イメージのプルに関するワークフロー
• Service の問題：ネットワーク接続のワークフロー
• DNS の失敗：DNS のトラブルシューティングワークフロー
• リソースの枯渇：パフォーマンス調査のワークフロー
• ストレージの問題：PVC バインドのワークフロー
• Deployment の停滞：ロールアウトのワークフロー

5. 対象を絞った修正を適用する

症状に応じた修正については、./references/common_issues.md を参照してください。

6. 検証して完了する

最終確認を実行します。

kubectl get pods -n <namespace> -o wide
kubectl get events -n <namespace> --sort-by='.lastTimestamp' | tail -20
kubectl rollout status deployment/<name> -n <namespace>

ユーザーから見える動作が正常で、新たな重大な警告イベントが発生しなければ、問題は解決です。

フローの例

例 1：payments 名前空間の CrashLoopBackOff

python3 ./scripts/pod_diagnostics.py payments-api-7c97f95dfb-q9l7k -n payments -o payments-diagnostics.txt
kubectl logs payments-api-7c97f95dfb-q9l7k -n payments --previous --tail=100
kubectl get deploy payments-api -n payments -o yaml | grep -A 8 livenessProbe

次に、./references/common_issues.md を開き、CrashLoopBackOff の解決策を適用してください。

例 2：サービスの DNS／接続障害

./scripts/network_debug.sh checkout checkout-api-75f49c9d8f-z6qtm
kubectl get svc checkout-api -n checkout
kubectl get endpoints checkout-api -n checkout
kubectl get networkpolicies -n checkout

次に、./references/troubleshooting_workflow.md の Service Connectivity Workflow に従ってください。

必須の手動コマンド

Pod のデバッグ

# View pod status
kubectl get pods -n <namespace> -o wide

# Detailed pod information
kubectl describe pod <pod-name> -n <namespace>

# View logs
kubectl logs <pod-name> -n <namespace>
kubectl logs <pod-name> -n <namespace> --previous  # Previous container
kubectl logs <pod-name> -n <namespace> -c <container>  # Specific container

# Execute commands in pod
kubectl exec <pod-name> -n <namespace> -it -- /bin/sh

# Get pod YAML
kubectl get pod <pod-name> -n <namespace> -o yaml

サービスとネットワークのデバッグ

# Check services
kubectl get svc -n <namespace>
kubectl describe svc <service-name> -n <namespace>

# Check endpoints
kubectl get endpoints -n <namespace>

# Test DNS
kubectl exec <pod-name> -n <namespace> -- nslookup kubernetes.default

# View events
kubectl get events -n <namespace> --sort-by='.lastTimestamp'

リソースの監視

# Node resources
kubectl top nodes
kubectl describe nodes

# Pod resources
kubectl top pods -n <namespace>
kubectl top pod <pod-name> -n <namespace> --containers

緊急時の操作

# Restart deployment
kubectl rollout restart deployment/<name> -n <namespace>

# Rollback deployment
kubectl rollout undo deployment/<name> -n <namespace>

# Force delete stuck pod
kubectl delete pod <pod-name> -n <namespace> --force --grace-period=0

# Drain node (maintenance)
kubectl drain <node-name> --ignore-daemonsets --delete-emptydir-data

# Cordon node (prevent scheduling)
kubectl cordon <node-name>

完了条件

以下をすべて満たしたら、トラブルシューティングセッションは完了です。

• クラスターのコンテキストと名前空間が確認されている。
• 関連する診断スクリプトの出力が取得されている。
• 根本原因が特定され、証拠（イベント／ログ／設定／状態）と関連付けられている。
• 影響を伴う操作の前に、スナップショットとロールバック計画が用意されている。
• 修正の検証コマンドで正常な状態が確認されている。
• 使用した参照パス（./references/troubleshooting_workflow.md または ./references/common_issues.md）がメモに記録されている。

関連ツール

Kubernetes のデバッグに役立つ追加ツール：

• kubectl-debug：高度なデバッグプラグイン
• stern：複数 Pod のログを追尾
• kubectx/kubens：コンテキストと名前空間の切り替え
• k9s：Kubernetes 用ターミナル UI
• lens：Kubernetes 用デスクトップ IDE
• Prometheus/Grafana：監視とアラート
• Jaeger/Zipkin：分散トレーシング