gke-ai-troubleshooting-node-unresponsive-timeout

GKE の応答しない TPU ノードと GPU ノードのトラブルシューティング（NodeStatusUnknown）

TPU ノードまたは GPU ノードの Compute Engine ホストで致命的なハードウェアエラー、カーネルパニック、またはマスク不可割り込み（NMI）によるロックアップが発生すると、ゲスト OS は応答を停止します。kubelet がハートビートを送信できなくなるため、ノードの Ready 条件は Reason: NodeStatusUnknown（Kubelet stopped posting node status.）を伴って Unknown になります。ノードプールでノードの自動修復が無効になっている場合、GKE はノードを修復しません。ノードは NotReady のままになり、ノード上の Pod が Terminating のままになることがあります。その結果、複数ホストの JobSet ワークロードが復旧できなくなります。

クレジット表記

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

前提条件

• ツール：Google Cloud SDK（gcloud）と kubectl をインストールします。
• Cloud Billing とプロジェクトの構成：有効な請求先アカウントが関連付けられていること（gcloud billing projects describe {project_id}）、認証済みであること（gcloud auth login）、対象プロジェクトが設定されていること（gcloud config set project {project_id}）を確認し、container.googleapis.com、 compute.googleapis.com、logging.googleapis.com、 monitoring.googleapis.com が有効になっていることを確認します。
• 必要な IAM ロール：
  • Kubernetes Engine 閲覧者（roles/container.viewer）
  • Compute 閲覧者（roles/compute.viewer）
  • Logs 閲覧者（roles/logging.viewer）
  • Monitoring 閲覧者（roles/monitoring.viewer）
  • 修復（[High Risk] の手順）の場合：Kubernetes Engine クラスタ管理者 （roles/container.clusterAdmin）
• ドキュメント：
  • GKE で NotReady ステータスのノードをトラブルシューティングする （セクション：「ノードのステータスと条件を確認する」、「ノードのプリエンプションを確認する」、「ノードが復旧したことを確認する」）
  • GKE Standard で TPU ワークロードをデプロイする （セクション：「TPU ノードとノードプールの健全性指標をモニタリングする」、「TPU スライスノードの自動修復を構成する」）
  • OOM イベントのトラブルシューティング
  • GKE ログを表示する （セクション：「システムログ」）
  • シリアルポート出力を表示する
  • カーネルパニックが原因の Linux VM 起動問題をトラブルシューティングする
  • ノードを自動修復する （セクション：「Autopilot と Standard の設定」、「Standard ノードプールでノードの自動修復が有効か確認する」、「最近の自動修復イベントに関する情報を取得する」、「既存の Standard ノードプールで自動修復を有効にする」、「修復の基準」、「ノード修復プロセス」、「TPU スライスノードでのノード自動修復」）
  • VM のシャットダウンと再起動のトラブルシューティング （セクション：「Cloud Audit Logs のクエリ」、「Cloud Audit Logs の確認」）

読み取り専用のルール：読み取り専用の診断コマンドのみを実行してください。ノードのドレイン、削除、再作成や、クラスタを変更するその他のコマンドは決して実行しないでください。修正方法はユーザーに提示し、ユーザー自身で適用してもらってください。

修正方法を推奨する場合は、その方法を説明するドキュメントのセクションにリンクしてください。

---

診断ワークフロー

ステップ 0：コンテキストを収集し、調査ウィンドウを設定する [Low Risk]

対象パラメーターを収集します。デフォルトでは、{issue_time} の前後 60 分のウィンドウ [{issue_time} - 30m, {issue_time} + 30m] をクエリします。

• {project_id}：Google Cloud プロジェクト ID
• {cluster_name}：GKE クラスター名
• {location}：クラスターのリージョンまたはゾーン
• {nodepool_name}：対象となる TPU または GPU ノードプール名
• {node_name}：応答しない GKE ノード名（およびその Compute Engine の {zone}）
• {issue_time}：RFC3339 形式の UTC インシデント発生時刻
• {start_time}：{issue_time} - 30m
• {end_time}：{issue_time} + 30m

---

ステップ 1：NodeStatusUnknown のハートビートタイムアウトを確認する [Low Risk]

1. Kubernetes ノードの状態を確認する：ノードの状態を調べ、Ready 条件が Unknown で、Reason: NodeStatusUnknown（Kubelet stopped posting node status.）であるかを確認するには、セクション ノードの状態と条件を確認するの手順に従います。
2. Cloud Logging をクエリする（読み取り専用の LQL）：[{start_time}, {end_time}] の期間について k8s_node および k8s_cluster ログをクエリし、コントロールプレーンが {node_name} とのハートビート接続を失った時刻を確認します。

(resource.type="k8s_node" OR resource.type="k8s_cluster")
resource.labels.cluster_name="{cluster_name}"
("{node_name}" AND ("NodeNotReady" OR "NodeStatusUnknown" OR "Kubelet stopped posting node status"))
timestamp >= "{start_time}" AND timestamp <= "{end_time}"

3. Cloud Monitoring をクエリする（読み取り専用の PromQL）：GKE システム指標 kubernetes.io/node/status_condition（kubernetes_io:node_status_condition、 GKE 1.32.1-gke.1357001+）を使用して Unknown 状態の継続時間を照合します。この指標については、 TPU ノードとノードプールの健全性指標をモニタリングするで説明されています。condition="Ready" および status="Unknown" でフィルタリングします。

kubernetes_io:node_status_condition{
  monitored_resource="k8s_node",
  cluster_name="{cluster_name}",
  node_name="{node_name}",
  condition="Ready",
  status="Unknown"
}

• 判断ロジック：
  • ノードの Ready 条件が True で、NodeStatusUnknown が存在しない場合は、応答しないノードのタイムアウトを除外し、ノードの修復やドレインではなく、ワークロードレベルのトラブルシューティング（例： OOM イベントのトラブルシューティング）に進みます。
  • Ready が Unknown（NodeStatusUnknown）の場合は、ステップ 2 に進みます。

---

ステップ 2：カーネルパニックのシリアルポート出力を調べる [Low Risk]

致命的なカーネルフリーズが発生すると、ゲスト OS はログを送信できなくなるため、ノードの VM のシリアルポート出力を確認します。

• Cloud Logging：シリアルポートのロギングが有効な場合（つまり、VM メタデータ serial-port-logging-enable が true に設定されている場合）、Cloud Logging の GKE システムログにはノードのシリアルポート出力が含まれます。詳しくは、セクション システムログをご覧ください。VM が停止している場合、自動修復によってすでに置き換えられている場合、または最新の出力より前の内容も必要な場合は、Cloud Logging を使用します。
• 実行中の VM：シリアルポート出力を表示するの手順に従って、{zone} 内の {node_name} のシリアルポート 1 の出力（--port=1 を指定した gcloud compute instances get-serial-port-output）を取得します。この方法で取得できるのは、各ポートの最新 1 MB の出力のみです。

カーネルパニックによる Linux VM の起動問題のトラブルシューティングを参照し、シリアルポート出力に記録される、文書化されたカーネルパニックやハードウェアクラッシュのパターン（Fatal Machine check、hung_task: blocked tasks、NMI: Not continuing など）を特定します。

---

ステップ 3：ノードの自動修復ステータスを確認する [Low Risk]

GKE が応答しないノードを修復していない理由を確認します。

• Autopilot クラスター：Autopilot では常にノードが修復され、この機能を無効にすることはできません（ Autopilot と Standard の設定を参照してください）。 設定の確認は省略し、修復履歴を確認してください。
• Standard クラスター：Standard ノードプールでノードの自動修復が有効になっていることを確認する の手順に従い、{nodepool_name} で autoRepair が有効になっているか確認してください。
• 修復履歴（両方のモード）：自動修復を有効にしていても、修復に失敗することがあります。 TPU スライスノードの自動修復を設定するに従い、 最近の自動修復イベントに関する情報を取得する で説明されている操作履歴で、失敗の理由を含む修復ステータスを確認してください。 クォータ不足が原因で失敗している場合は、ユーザーに Google Cloud のアカウント担当者に連絡して、クォータを増やすよう伝えてください。

---

ステップ 4：Compute Engine のシステムイベントを確認する [Low Risk]

{issue_time} 前後に発生した {node_name} のシステムイベントを一覧表示するには、 Cloud Audit Logs のクエリのセクションの手順に従ってください。 method フィールドを同じドキュメントの「Cloud Audit Logs の確認」セクションにある表と比較し、次のイベントを探します。

• compute.instances.hostError：物理ホストのハードウェアまたはソフトウェアの問題により、VM がクラッシュしました。
• compute.instances.preempted：Compute Engine が Spot VM またはプリエンプティブル VM をプリエンプトしました。プリエンプトされたノードについては、 ノードのプリエンプションを確認するも参照してください。
• compute.instances.automaticRestart：Compute Engine が hostError または terminateOnHostMaintenance イベントの後に VM を再起動しました。
• compute.instances.guestTerminate：VM のオペレーティングシステムがシャットダウンを開始しました。

---

ステップ 5：解決 [High Risk]

ガードレール：

• 応答しないノード上で、Terminating 状態のまま停止している Pod を絶対に強制削除しないでください。 強制削除では、kubelet が Pod の停止を確認するまで待機しないため、古い Pod がまだ実行中の状態で、置き換え用 Pod が起動する可能性があります。 ステートフルセットの Pod を強制削除するを参照してください。
• GKE が管理する Compute Engine VM インスタンスを直接削除（gcloud compute instances delete）しないでください。代わりに、ノードが NodeStatusUnknown を報告している時間（ステップ 1）を確認し、シリアルコンソールの出力（ステップ 2）を確認したうえで、以下の手順に記載されているノードの自動修復に任せてください。

1. ノードの自動修復を有効にする（Standard クラスタのみ）：
   • Autopilot クラスタではノードが常に自動修復されるため、この手順は省略してください。
   • マルチホスト TPU スライスのノードプールで自動修復を有効にする前に、ノードの修復が必要になると GKE はノードプール全体を再作成することをユーザーに伝えてください（ステップ 2 を参照）。
   • {nodepool_name} で autoRepair が無効になっている場合は、ユーザーが自分で変更を適用できるよう、既存の Standard ノードプールで自動修復を有効にするとTPU スライスノードの自動修復を設定するへのリンクを案内してください。
2. GKE にノードを修復させる：
   • GKE は、NotReady を報告したノード、または所定の時間しきい値を過ぎてもステータスを報告しないノードを、ドレインして再作成することで修復することを説明し、ノードの自動修復の「修復の条件」と「ノードの修復プロセス」の各セクションへのリンクを案内してください。GKE はドレインの完了まで 1 時間待機します。ドレインが完了しない場合、GKE はノードをシャットダウンして新しいノードを作成します。GKE がノードを再作成する前に、ドレインの完了まで 1 時間待機することをユーザーに伝えてください。
   • マルチホスト TPU スライスのノードプールについては、TPU スライスノードのノード自動修復に記載されているとおり、ノードプール全体が再作成されることを伝えてください。
3. ノードの復旧を確認する：
   • 修復の完了後、ノードが復旧したことを確認するセクションの手順に従って、修復されたノードが Ready ステータスに戻ったことを確認し、JobSet Pod が再び実行されていることを確認してください。