gke-ai-troubleshooting-handle-disruption-gpu-tpu

GPU および TPU の中断に関するトラブルシューティング

クレジット表記

必ずお読みください：gcloud、REST API、または MCP コマンドを実行する前に、使用方法とクレジット表記を必ずお読みください。ターミナルで直接実行するコマンドの場合（生成されたスクリプト、Terraform、ユーザーコード内では実行しないでください）、gcloud の前に CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:gke-ai-troubleshooting-handle-disruption-gpu-tpu)" を付け、User-Agent ヘッダーに agent-skills/1.0 (skill:gke-ai-troubleshooting-handle-disruption-gpu-tpu) を追加してください。

🔍 診断ワークフロー

ステップ 0：コンテキストの取得

• 必須：ユーザーが実際のワークロードの中断、ノードのクラッシュ、予期しない再起動のデバッグまたは調査を依頼していて、クラスターの詳細情報が不足している場合、理論や一般的な診断コマンドを提示する前に、直ちに作業を中断し、不足している必須パラメーター（project_id、location、cluster_name、timestamp）をすべて要求する必要があります。ユーザーが汎用的に再利用できるランブックを明示的に求めている場合、またはオフライン分析用の静的なテレメトリー／ログの完全なダンプを提供している場合に限り、コンテキストの取得を省略できます。
• 任意：node_name、workload_name、workload_namespace、nodepool_name。

ステップ 1：[低リスク] 予定されているメンテナンスの確認

• 操作：ノードに、間近に予定されている中断を示すメンテナンス予定ラベルがあるかどうかを確認するため、kubectl の実行を提案します。

• コマンド例：

  kubectl get nodes -l cloud.google.com/scheduled-maintenance-time -L cloud.google.com/scheduled-maintenance-time
  

• 解釈：SCHEDULED-MAINTENANCE-TIME 列には、VM のメンテナンスが予定されている Unix エポック時刻が表示されます。このラベルが存在する場合、中断が確実に発生します。

ステップ 2：[低リスク] Cloud Monitoring による調査（PromQL）

• 操作：利用可能なモニタリングツールを呼び出すか、手動確認用の PromQL を提示します。

• 必須のモニタリング規則：継続的なモニタリングや中断の追跡を推奨する場合は必ず、interruption_reason="HW/SW Maintenance" でフィルタリングしたメトリクス kubernetes_io:node_interruption_count を使用する PromQL クエリを明示してください。この特定の PromQL メトリクス式を提示せずに、一般的な Cloud Monitoring ダッシュボードや Metrics Explorer を提案しないでください。

• クエリ例：

  # ノードのホストメンテナンスイベントを取得
  sum by (interruption_type,interruption_reason)( sum_over_time( kubernetes_io:node_interruption_count{monitored_resource="k8s_node", interruption_reason="HW/SW Maintenance"}[${__interval}]))
  

  # ノードプールごとに集計した中断回数を確認
  sum by (node_pool_name,interruption_type,interruption_reason)( sum_over_time( kubernetes_io:node_pool_interruption_count{monitored_resource="k8s_node_pool", interruption_reason="HW/SW Maintenance", node_pool_name="{nodepool_name}" }[${__interval}]))
  

• 解釈：kubernetes_io:node_interruption_count が interruption_reason="HW/SW Maintenance" に対して 0 より大きい値を示す場合、基盤となる Compute Engine VM が、予定されていたホストメンテナンスによって中断されたことを示します。

ステップ 3：[低リスク] Cloud Logging とノードのテイントによる調査

• アクション：query_logs を呼び出すか、ユーザーに GKE ログをフィルタリングして現在進行中のホストメンテナンスイベントを確認し、ノードのテイントも確認するよう案内します。
• ガイダンス：Cloud Logging で cloud.google.com/active-node-maintenance が ONGOING に設定されている記録を探します。GKE が終了予定のノードをコーディングして新しいワークロードのスケジュールを防いでいるか確認するには、cloud.google.com/impending-node-termination:NoSchedule テイントが存在するか確認します（GKE のイベントログ、または kubectl describe node で直接確認できます）。
• 解釈：
  • cloud.google.com/active-node-maintenance が ONGOING に設定されている場合、ホストメンテナンスにより GKE がワークロードを停止していることを意味します。
  • cloud.google.com/impending-node-termination:NoSchedule テイントは、終了予定のノードで新しい Pod がスケジュールされないように、GKE がそのノードをコーディングしていることを意味します。このテイントを許容するよう推奨してはいけません。

ステップ 4：結論と解決策

• アクション：調査結果をユーザーに要約して伝え、ホストメンテナンスイベントが確認された場合、または予定されている場合は、適切な緩和策を提案します。
• 報告ルール：重要な情報のみを報告します。障害が Compute Engine のホストメンテナンスによって発生し、特に基盤となる GPU／TPU ノードに影響していることを示す情報に絞ってください。生ログをそのまま出力してはいけません。
• 否定的な調査結果による原因の除外：ノードのメンテナンス予定ラベル、PromQL の中断回数、アクティブなメンテナンスログのすべてで結果が陰性または空の場合、Compute Engine のホストメンテナンスが障害の原因ではなかったと明確に結論づけます。OOMKill イベント、CUDA ランタイムエラー、リソース制限など、アプリケーションレベルの原因を調査するようユーザーに案内し、ホストメンテナンスの緩和策を主な解決策として提案してはいけません。
• 必須のワークロード保護策 3 点：GPU／TPU ノードでホストメンテナンスが確認された場合、または予想される場合は、相互に補完する以下 3 つの緩和策を必ずまとめて推奨します。
  1. グレースフルな終了を設定する：状態の保存に時間が必要なワークロード（たとえば、Orbax を使用してチェックポイントを保存する ML フレームワーク）については、ガイドに従って 障害への対応を有効にする とともに、ノードのシャットダウン前に SIGTERM シグナルを処理できるよう spec.terminationGracePeriodSeconds（最大 60 分）を設定します。
  2. オポチュニスティックメンテナンスを有効にする：GKE が GPU／TPU ノードのアイドル状態を検知したときにメンテナンスを自動的に開始するには、 オポチュニスティックメンテナンス を設定します。
  3. PodDisruptionBudgets（PDB）を設定する：エビクションや中断の間、minAvailable レプリカ数を維持できるよう、ワークロードで PodDisruptionBudget を使用していることを確認します。