gke-ai-troubleshooting-tpu-vm-repair-stuck

Compute Engine の修復状態（REPAIRING）で停止した GKE TPU VM のトラブルシューティング

このスキルでは、VM のステータス、ホストイベント、GKE の修復ステータスを確認し、Compute Engine を直接変更せずに GKE 経由で復旧します。

帰属情報

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

前提条件

• ツール：
  • gcloud のインストールと初期化（認証とプロジェクトの選択を含みます）については、 始める前にに従ってください。
  • kubectl と必要なプラグインのインストールについては、 kubectl のインストール および 必要なプラグインのインストールに従ってください。
• Cloud Billing とプロジェクトの構成：プロジェクトに有効な Cloud Billing アカウントがあることを確認してください。 始める前にに従って gcloud を初期化し、Google Kubernetes Engine API (container.googleapis.com) を有効にしてください。また、Compute Engine API (compute.googleapis.com) と Cloud Logging API (logging.googleapis.com) が有効であることを確認し、 kubectl 用にクラスタ情報を保存するに従って kubectl のクラスタ認証情報を構成してください。
• 必要な IAM ロール：
  • Kubernetes Engine Viewer (roles/container.viewer)
  • Compute Viewer (roles/compute.viewer)
  • Logs Viewer (roles/logging.viewer)
  • ステップ 5 の項目 1 でノードの自動修復を有効にするユーザーには、Kubernetes Engine Cluster Admin (roles/container.clusterAdmin)
• ドキュメント：
  • MIG とマネージドインスタンスに関する情報を表示する （セクション：「MIG の一覧表示」、「マネージドインスタンスのステータスを確認する」）
  • Compute Engine インスタンスのライフサイクル （セクション：「REPAIRING 状態」）
  • VM のシャットダウンと再起動のトラブルシューティング （セクション：「Cloud Audit Logs のクエリ」、「Cloud Audit Logs の確認」）
  • kubectl のクラスタアクセスを構成する （セクション：「kubectl のインストール」、「必要なプラグインのインストール」、「kubectl 用にクラスタ情報を保存する」）
  • ノードプールを追加、管理する （セクション：「Standard クラスタでノードプールを表示する」、「特定のノードプールに Pod をデプロイする」）
  • NodeNotReady 状態のトラブルシューティング （セクション：「ノードのステータスと条件を確認する」、「ノードのプリエンプションを確認する」）
  • GKE の TPU について （セクション：「マルチホスト TPU スライスのノードプール」）
  • カスタムスケジューラで動的スライシングを使用する （セクション：「要件」、「ノードとパーティションのステータスを確認する」、「Slice カスタムリソースのステータスを監視する」、「ハードウェアのメンテナンスと障害」）
  • GKE の動的スライシングについて （セクション：「動的スライシング構成の主な特性」）
  • GKE の All Capacity モードで TPU をデプロイする （セクション：「ノード障害を管理する」、「ノードの障害と復旧」）
  • All Capacity モードで障害のある TPU ホストを報告し、修復する （セクション：「障害ホストの報告プロセスについて」、「障害ホストの報告操作を確認する」）
  • ノードの自動修復 （セクション：「Autopilot と Standard の設定」、「修復条件」、「ノードの修復プロセス」、「Standard ノードプールでノードの自動修復が有効になっていることを確認する」、「既存の Standard ノードプールで自動修復を有効にする」、「最近の自動修復イベントに関する情報を取得する」、「TPU スライスノードでのノード自動修復」）
  • GKE Standard で TPU ワークロードをデプロイする （セクション：「始める前に」、「TPU スライスノードの自動修復を構成する」）
  • サポートを受ける （セクション：「サポートに問い合わせる前に」、「効率的なサポートのための推奨事項」）
  • REST リソース：projects.locations.clusters.nodePools （セクション：「リソース：NodePool」）

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

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

---

診断ワークフロー

ステップ 0：コンテキストを収集する [Low Risk]

対象のパラメーターを収集します。

• {project_id}：Google Cloud プロジェクト ID
• {cluster_name}：GKE クラスター名
• {location}：クラスターのリージョンまたはゾーン
• {cluster_mode}：クラスターのモード（Autopilot または Standard）
• {tpu_version}：TPU のバージョン（Ironwood tpu7x、TPU v6e、v5p、v5e、v4 など）と、ノードプールがシングルホストまたはマルチホストの TPU スライスノードプールのどちらか
• {nodepool_name}：TPU ノードプール名
• {group_name} と {zone}：ノードプールを支えるマネージドインスタンスグループ（MIG）の名前とゾーン
  • Standard クラスターの場合は、Standard クラスターでノードプールを表示するの手順に従って {nodepool_name} を詳細表示し、その instanceGroupUrls フィールドを確認します（リソース：NodePoolを参照）。
  • Autopilot クラスターの場合（または {nodepool_name} が不明な場合）は、MIG を一覧表示するの手順に従って {project_id} 内のマネージドインスタンスグループを一覧表示し、{group_name} と {zone} を特定します。
• {instance_name}：影響を受けている TPU VM 名（判明している場合）。ユーザーが {instance_name} を把握していない場合は、ステップ 1 で REPAIRING 状態のインスタンスを特定します。
• {issue_time}：インシデントのタイムスタンプ（RFC3339 UTC、判明している場合）

---

ステップ 1：マネージドインスタンスグループ内の VM のステータスを確認する [Low Risk]

{group_name} 内のインスタンスについて、ステータス（STATUS／instanceStatus）と現在のアクション（ACTION／currentAction）を一覧表示するには、マネージドインスタンスのステータスを確認するの手順に従います。

• 分析：
  • STATUS（instanceStatus）が REPAIRING：内部エラーが発生したか、メンテナンスのためホストサーバーが利用できないため、Compute Engine が VM を修復しています。修復中は VM を使用できません。REPAIRING 状態を参照してください。{instance_name} を記録して、ステップ 2 に進みます。
  • REPAIRING 状態のインスタンスがない（すべてのインスタンスが ACTION NONE で RUNNING を報告している場合、または マネージドインスタンスのステータスを確認するによれば「インスタンスが置き換えられています」を意味する ACTION RECREATING など、別のステータスまたはアクションを報告している場合）：ノードのステータスと条件を確認するの手順に従って各ノードのステータスと条件を確認し、該当する関連スキルに引き継ぎます。
    • ノードの Ready 条件が Unknown（NodeStatusUnknown）の場合は、gke-ai-troubleshooting-node-unresponsive-timeout に引き継ぎます。
    • 別の理由でノードが Ready ではない場合は、gke-node-notready に引き継ぎます。
    • 修復の基準にあるとおり、「Ready ステータスを報告するノードは正常と見なされる」にもかかわらず、すべてのノードが Ready で、ワークロードの Pod がまだ Pending の場合は、gke-workload-troubleshooting に引き継ぎます。

---

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

{issue_time} の前後に {instance_name} で発生したシステムイベントを一覧表示するには、 Cloud Audit Logs のクエリのセクションにある手順に従います。同じドキュメントの Cloud Audit Logs の確認 セクションの表と method フィールドを照合します。

• compute.instances.hostError、 compute.instances.terminateOnHostMaintenance、または compute.instances.automaticRestart：一致するシステムイベントログの エントリとタイムスタンプを記録し、ステップ 3 と 4 に進みます。
• compute.instances.preempted：Compute Engine が Spot VM または プリエンプティブル VM のプリエンプションを実行しました。影響を受けたワークロードが JobSet の場合は、 gke-ai-troubleshooting-jobset-interruption に引き継ぎます。それ以外の場合は、 ノードのプリエンプションを確認する の手順に従います。
• 表に記載されているメソッドがない場合、または別のメソッドの場合：Cloud Audit Logs の確認 の注記にあるように、VM が再起動し、クエリ結果に記載されているメソッドが表示されない場合、 VM のオペレーティングシステムが再起動を開始した可能性が高いです。ステップ 1 で VM がまだ REPAIRING 状態の場合（または compute.instances.reportHostAsFaulty などのメソッドが表示される場合）は、ステップ 3 と 4 に進みます。

---

ステップ 3：ノードのステータスとスライスへの影響を確認する [Low Risk]

ノードのステータスと状態を確認する の手順に従い、クラスター内のノードのステータスと状態を確認して、 ノードの ProviderID フィールドを使って {instance_name} と照合します。ノードを {nodepool_name} に絞り込むには、 特定のノードプールに Pod をデプロイする に記載されている cloud.google.com/gke-nodepool ノードラベルを使用します。

• {instance_name} のノードが Ready を報告しており（修復の条件によると、「Ready ステータスを報告するノードは正常と見なされます」）、VM が REPAIRING ではなくなっている場合は、ステップ 5 の項目 4 に進みます。
• それ以外の場合は、ノードプールの構成に基づいて、異常なノードがノードプールに与える影響を判断します。
  • シングルホスト TPU スライス ノードプール：TPU スライスノードの自動修復を構成するによると、「シングルホスト TPU スライス ノードプールでは、異常な TPU ノードのみが自動修復されます」。
  • 動的スライシング ノードプール：{nodepool_name} が動的スライシングを使用しているか確認するには、要件を参照してください。動的スライシングには、Standard クラスタ、Ironwood（tpu7x）、All Capacity モードの予約が必要です。Ironwood（tpu7x）を使用する Standard クラスタの場合、ノードとパーティションのステータスを確認するのステップ 2 に示すように、ノードに cloud.google.com/gke-accelerator-topology-mode: PROVISION_ONLY が設定されているか確認してください（動的スライシング構成の主な特性によると、「動的スライシングでは段階的なプロビジョニングが使用されます」）。ハードウェアのメンテナンスと障害によると、「お客様がメンテナンスを開始した場合、またはハードウェアのフェイルオーバーが発生した場合、ノードプール全体ではなく、対象のノードのみが影響を受けます」。アクティブな動的サブスライスでは、Slice カスタムリソースが FAILED に遷移し、スケジューラはほかの利用可能で正常なノード上にスライスを再作成しようとします。Slice カスタムリソースのステータスを監視するに従って Slice のステータスを確認してください。Slice カスタムリソースが FAILED またはほかの非アクティブな状態の場合は、ステップ 4 で VM の修復を確認するとともに、Slice のトラブルシューティングを gke-ai-troubleshooting-tpu-dynamic-slices-monitoring に引き継いでください。
  • TPU All Capacity モードのノードプール：ノード障害の管理およびノード障害と復旧によると、TPU All Capacity モードでは、ハードウェア障害などの問題で VM に障害が発生した場合、Google Cloud は「同じホスト上で VM の復旧（インプレース修復）を試みます」。障害が発生したノードのステータスは NotReady となり、ノードプールのステータスは ERROR に変化しません。
  • マルチホスト TPU スライス ノードプール（動的スライシングまたは All Capacity モードを使用しない場合）：マルチホスト TPU スライス ノードプールのセクションによると、マルチホスト TPU スライス ノードプール内の VM は、単一のアトミックな単位として扱われます。スライス内のノードに修復が必要になると、GKE は TPU スライス内のすべての VM をシャットダウンし、ワークロード内のすべての Kubernetes Pod を強制退去させます。Pod を再度スケジュールできるのは、スライス内のすべての VM が稼働状態になった後です。

---

ステップ 4：ノードの自動修復の状態と障害ホストの報告を確認する [Low Risk]

GKE または Compute Engine がノードを修復しているか確認します。

1. ノードの自動修復が有効かどうかを確認します：
   • Autopilot クラスター：Autopilot では常にノードが修復され、この機能を無効にすることはできません（ Autopilot と Standard の設定を参照してください）。
   • Standard クラスター：Standard ノードプールでノードの自動修復が有効になっていることを確認する に従い、{nodepool_name} で autoRepair が有効かどうかを確認します。
2. GKE の修復オペレーション履歴を確認します：TPU スライスノードの自動修復を構成するに従い、 最近の自動修復イベントに関する情報を取得する で説明されているオペレーション履歴で、失敗理由を含む修復ステータスを確認します。
   • クォータ不足が原因で修復オペレーションが失敗した場合は、クォータの増加について Google Cloud のアカウント担当者に問い合わせるようユーザーに伝えます。
   • autoRepair が有効で、修復オペレーションがまだ記録されていない場合は、ノードが正常でない状態になってからの時間（{issue_time}、またはステップ 3 の Ready 条件の LastTransitionTime）を確認します。 修復の基準によると、ノードが一定の時間（約 10 分）の間 NotReady を報告した場合、またはステータスをまったく報告しない場合に、GKE は修復を開始します。ノードが NotReady（またはステータスなし）を報告している時間が約 10 分未満の場合は、その時間を過ぎてからオペレーション履歴を再確認します。約 10 分を超えているにもかかわらず修復オペレーションがなく（項目 3 に該当する All Capacity モードの障害ホスト報告もない場合）、ステップ 5 の項目 3 に進んでエスカレーションします。
3. All Capacity モードの TPU ノードプールでは、障害ホストの報告を確認します： 障害ホスト報告のプロセスについてによると、ユーザーが障害ホストを報告した後、TPU VM は停止し、状態が REPAIRING に変わります。「ホストの修復プロセスには 3～14 日、またはそれ以上かかることがあります。」All Capacity モードの予約で REPAIRING 状態の VM をエスカレーションする前に、 障害ホスト報告オペレーションを確認する に従い、{instance_name} に対する compute.instances.reportHostAsFaulty オペレーションがあるか確認します。

---

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

ガードレール：

• Compute Engine を通じて、GKE 管理下のインスタンスグループや VM を絶対に直接変更しないでください。たとえば、gcloud compute instances delete や、グループを変更する gcloud compute instance-groups managed コマンドは使用しないでください。ノードプールは GKE を通じて管理します。
• ノードプール内のノードに対して kubectl delete node を絶対に実行しないでください。 Autopilot と Standard の設定によると、自動修復が無効な状態で kubectl を使って正常でないノードを削除すると、基盤となる VM がクラスターから孤立する可能性があり、その VM の料金が引き続き発生します。

1. ノードの自動修復を有効にする（Standard クラスタのみ）：
   • Autopilot クラスタでは常にノードが自動修復されるため、この手順は省略してください。
   • 動的スライシングも All Capacity モードも使用していないマルチホスト TPU スライスノードプールで、ユーザーが自動修復を有効にする前に、ノードの修復が必要になると GKE がノードプール全体を再作成することを伝えてください（この手順の項目 2 を参照）。
   • {nodepool_name} で autoRepair が無効になっている場合は、既存の Standard ノードプールで自動修復を有効にするおよびTPU スライスノードの自動修復を構成するにユーザーを案内し、自分で変更を適用できるようにしてください。ユーザーには Kubernetes Engine Cluster Admin ロール（roles/container.clusterAdmin）が必要です。
2. GKE または All Capacity モードにノードまたはスライスを修復させる：
   • シングルホスト TPU スライスノードプール：TPU スライスノードの自動修復を構成するによると、「シングルホスト TPU スライスノードプールでは、異常な TPU ノードのみが自動修復されます。」ノードの修復プロセスによると、単一ノードの修復では、GKE はノードをドレインし、ドレインが完了するまで 1 時間待機します。ドレインが完了しない場合、GKE はノードをシャットダウンして新しいノードを作成します。
   • マルチホスト TPU スライスノードプール（動的スライシングも All Capacity モードも使用していない場合）：TPU スライスノードのノード自動修復およびTPU スライスノードの自動修復を構成するによると、マルチホスト TPU スライスノードプールの TPU スライスノードに異常があり、自動修復が必要な場合、ノードプール全体が再作成されます。
   • 動的スライシングのノードプール：ハードウェアのメンテナンスと障害によると、ノードプール全体ではなく、対象のノードのみが影響を受けます。また、動的サブスライシングでは、スケジューラが、失敗したスライスを他の利用可能な正常なノード上に再作成しようとします。Slice カスタムリソースの作成に失敗するか、FAILED のままになる場合は、gke-ai-troubleshooting-tpu-dynamic-slices-monitoring に引き継いでください。
   • ホスト障害レポートがある TPU All Capacity モード：ステップ 4 の項目 3 で {instance_name} に対する compute.instances.reportHostAsFaulty オペレーションが見つかった場合（ホスト障害レポートのオペレーションを確認するで追跡）、VM が停止したままになっているとしてエスカレーションしないでください。ホスト障害レポートのプロセスを理解するによると、修復中は VM が停止し、修復完了後に同じホストで再起動することをユーザーに伝えてください。また、「ホストの修復プロセスには 3～14 日、またはそれ以上かかることがあります。」
3. 修復が開始されない、または完了しない場合は Cloud Customer Care に連絡する：
   • VM が REPAIRING のままの場合（3～14 日かかる All Capacity モードのホスト障害修復を待っている場合を除く）、autoRepair が有効でステップ 4 に修復オペレーションがないのに、修復の基準に記載された約 10 分のしきい値を超えてノードが NotReady のまま（またはステータスが報告されないまま）の場合、あるいはオペレーション履歴に、クォータが原因ではない修復の失敗が示されている場合は、サポートに問い合わせる前におよび効率的なサポートを受けるための推奨事項をユーザーに案内し、Cloud Customer Care に連絡してもらってください。効率的なサポートを受けるための推奨事項に記載されている詳細に加えて、ノードプール名、インスタンス名、ステップ 2 のシステムイベントログエントリ、ステップ 4 の修復オペレーション名も含めてください。
4. 復旧を確認する：
   • ステップ 1 とステップ 3 を繰り返してください。復旧が完了すると、{group_name} 内のすべてのインスタンスで RUNNING とアクション NONE が報告され、{nodepool_name} 内のすべてのノードが Ready になります。
   • インスタンスで RUNNING とアクション NONE（または別のステータスやアクション）が報告されているのに、ノードがまだ Ready でない場合は、ステップ 1 の引き継ぎ先（gke-ai-troubleshooting-node-unresponsive-timeout または gke-node-notready）に従うか、この手順の項目 3 に従って Cloud Customer Care にエスカレーションしてください。