gke-ai-troubleshooting-tpu-slice-mig-stuck-updating

不安定な MIG によってブロックされている GKE TPU スライスの作成をトラブルシューティングする

このスキルは、TPU ノードプールを支える Compute Engine マネージド インスタンス グループ（MIG）が安定していない（status.isStable: false）場合に発生する、GKE TPU Dynamic Slice の作成失敗と JobSet のスケジューリング遅延の診断に役立ちます。

SliceCreationFailed ステータス理由は、前提条件を満たしていない（たとえば、必要な Compute Engine リソースがない）か、事前チェックに失敗したためにスライスの作成が失敗したことを示します（カスタムスケジューラで動的スライスを使用するを参照）。インスタンスの作成、更新、または修復が続いている MIG も、確認すべき原因の 1 つです。このスキルでは、まずスライスのステータスを確認し、次に基盤となる MIG の安定性を確認します。

帰属情報

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

前提条件

• Google Cloud SDK とツール:
  • gcloud のインストールと初期化（プロジェクトの選択と認証）、および GKE API の有効化については、 始める前にに従ってください。
  • kubectl のインストールとクラスタ認証情報の設定については、 kubectl のインストールとクラスタアクセスの設定の「kubectl のインストール」、「必要なプラグインのインストール」、「kubectl 用のクラスタ情報の保存」の各セクションに従ってください。
• API の有効化と課金:
  • プロジェクトに有効な Cloud Billing アカウントがあることを確認してください。
  • API を有効にします：container.googleapis.com、compute.googleapis.com、および logging.googleapis.com。
• 必要な IAM ロール:
  • Logs Viewer（roles/logging.viewer）：MIG のエラーを調査するため、Cloud Audit Logs を確認します。
  • Compute Viewer（roles/compute.viewer）：MIG の安定性（isStable）とインスタンスの進行状況を確認します。
  • Kubernetes Engine Viewer（roles/container.viewer）：Slice カスタムリソース（slices.accelerator.gke.io）、ノード、クラスタ操作を確認します。
• ドキュメント:
  • カスタムスケジューラを使用した動的スライス （セクション：「始める前に」、「Slice カスタムリソースの作成」、「Slice カスタムリソースのステータスの監視」、「ノードとパーティションのステータスの確認」、「ノードプールのアップグレード」）
  • kubectl のインストールとクラスタアクセスの設定 （セクション：「kubectl のインストール」、「必要なプラグインのインストール」、「kubectl 用のクラスタ情報の保存」）
  • ノードプールの追加と管理 （セクション：「Standard クラスタのノードプールを表示する」）
  • MIG とマネージドインスタンスに関する情報の表示 （セクション：「MIG が安定しているかどうかを確認する」、「マネージドインスタンスのステータスを確認する」、「インスタンスエラーを一覧表示する」）
  • MIG 内の VM 構成の更新を自動的に適用する （セクション：「更新のロールアウトが完了したかどうかを確認する」）
  • クラスタのコントロールプレーンまたはノードプールを手動でアップグレードする （セクション：「ノードプールのアップグレードステータスを確認する」、「ノードプールのアップグレードをキャンセルする」、「ノードプールのアップグレードを再開する」、「ノードプールのアップグレードをロールバックする」）
  • ノードの自動修復 （セクション：「最近の自動修復イベントに関する情報を取得する」）
  • GKE Standard ノードプールのトラブルシューティング （セクション：「問題：リソース不足によりノードプールの作成に失敗する」）
  • GKE の TPU のトラブルシューティング （セクション：「TPU リクエストを満たすためのクォータが不足している」、「TPU リクエストを満たすための TPU リソースが不足している」）
  • REST リソース：projects.locations.clusters.nodePools （セクション：「リソース：NodePool」）
  • Kueue と TAS を使用した動的スライスのスケジューリング （セクション：「スライスのステータスを監視する」）
  • GKE の TPU について
  • サポートを受ける （セクション：「サポートに問い合わせる前に」）

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

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

---

診断ワークフロー

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

ユーザープロンプトまたは環境から、必要なコンテキストパラメーターを収集します。

• {project_id}、{cluster_name}、{location}、{nodepool_name}、{issue_time}。
• {mig_name} と {zone}：{nodepool_name} を支えるマネージド インスタンス グループの名前とゾーンです。ノードプールの instanceGroupUrls フィールドから取得してください（Standard クラスターでノードプールを表示するおよびリソース：NodePoolを参照してください）。 {nodepool_name} または {mig_name} が失敗した Slice からまだ特定できない場合は、ノードとパーティションのステータスを確認するに従って、影響を受けたパーティション、ノード、およびバックエンドの MIG を特定してください。
• 時間範囲：デフォルトでは、60 分間の範囲 [{issue_time} - 30m, {issue_time} + 30m]（{start_time} から {end_time}）をクエリします。

---

ステップ 1：スライス作成の失敗と MIG エラーを検出する [Low Risk]

1. Slice のステータスとパーティションノードを調べる：Slice カスタムリソースの Status.Conditions を確認し、ステータスの理由が SliceCreationFailed であるかを調べます。影響を受けたパーティション、ノード、および {mig_name} は、カスタムスケジューラで動的スライシングを使用するの「Slice カスタムリソースのステータスを監視する」と「ノードとパーティションのステータスを確認する」の各セクション、およびスライスのステータスを監視するに従って特定してください。
2. Cloud Logging で MIG エラーをクエリする：{mig_name} を特定したら（または特定でき次第、結果を {mig_name} に絞り込んで）、次の Cloud Logging クエリを実行し、[{start_time}, {end_time}] の期間にバックエンドのインスタンス グループ マネージャーで発生したエラーを検出します。

   resource.type="gce_instance_group_manager"
   resource.labels.instance_group_manager_name="{mig_name}"
   severity>=ERROR
   timestamp >= "{start_time}" AND timestamp <= "{end_time}"
   

• 調査結果：
  • Slice のステータスに SliceCreationFailed が報告されている場合、またはログにインスタンス グループのエラーが示されている場合は、ステップ 2 に進みます。
  • 該当するエラーログがなく、TPU Slice のステータスが ACTIVE の場合は、MIG の不安定さを原因から除外し、ワークロードの設定を確認してください。

---

ステップ 2：MIG の安定性を確認する（status.isStable）[低リスク]

{mig_name} の MIG が安定しているかどうかを確認するに従って、{mig_name} の安定性（status.isStable）とバージョンの目標ステータス（status.versionTarget.isReached）を確認します。

• 各フィールドの意味：
  • status.isStable: false：変更が実行中または保留中であるか、MIG 自体が変更されています。ステップ 3 に進みます。
  • status.versionTarget.isReached: false：少なくとも 1 つのインスタンスで、まだ目標バージョンが実行されていません（MIG で VM 構成の更新を自動的に適用するを参照）。ステップ 3 に進みます。
  • status.isStable: true かつ status.versionTarget.isReached: true：変更中または変更が予定されているインスタンスはなく（すべてのインスタンスで currentAction が NONE）、MIG 自体も変更されていません。これにより、MIG の不安定さが原因ではないと判断できます。それでも Slice が SliceCreationFailed の場合は、gke-ai-troubleshooting-tpu-dynamic-slices-monitoring に引き継ぐか、カスタムスケジューラで動的スライスを使用するの「Slice カスタムリソースを作成する」と「ノードとパーティションのステータスを確認する」のセクションに従ってください。

---

ステップ 3：失敗または停滞しているインスタンスの操作を特定する [低リスク]

{mig_name} の個々のインスタンスの状態（currentAction と instanceStatus）を確認し、最新のエラーを一覧表示するために、「マネージドインスタンスのステータスを確認する」と「インスタンスエラーを一覧表示する」のセクションを案内します（両方のセクション名とドキュメントのタイトルを含めてください）。

• エラーに ZONE_RESOURCE_POOL_EXHAUSTED_WITH_DETAILS や QUOTA_EXCEEDED などの容量または割り当て量のエラーが表示される場合は、ステップ 5 の項目 2 に進みます。
• それ以外の場合は、ステップ 4 に進み、ノードプールのアップグレードまたは自動修復の操作を確認します。

---

ステップ 4：ノードプールの操作を確認する [低リスク]

インスタンスの変更が続いている MIG は、ノードプールのアップグレードまたは修復が原因である可能性があります。

1. ノードプールのアップグレードを確認する：ノードプールのアップグレード ステータスを確認するに従ってクラスタの操作を一覧表示し、[{start_time}, {end_time}] の期間に {nodepool_name} を対象とするアップグレード操作を探します。また、動的スライスのアップグレード要件（必要なサージ設定と、アップグレード前にアクティブなスーパー スライスを削除すること）について、ノードプールをアップグレードするも確認してください。
   • アップグレード操作が実行中の場合は、ステップ 5 の項目 1 または項目 3 に進みます。
   • アップグレード操作がキャンセルされた、失敗した、または未完了の場合は、ステップ 5 の項目 4 に進みます。
2. 自動ノード修復を確認する：最近の自動修復イベントに関する情報を取得するに従って、{nodepool_name} の修復操作を確認します。
   • ノードの自動修復操作が実行中の場合は、ステップ 5 の項目 1 に進みます。
3. 不安定な MIG の原因となる操作やエラーがない場合：ステップ 5 の項目 5 に進み、Cloud Customer Care に問い合わせます。

---

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

ガードレール：Compute Engine を通じて、GKE が管理するインスタンスグループや VM を直接変更しないでください。 ノードプールは GKE を通じて管理してください。

1. 進行中の更新または自動修復が完了するまで待つ：ノードプールのアップグレードまたは自動修復がまだ進行中の場合は、MIG が安定しているかどうかを確認するに従って、MIG が安定する（status.isStable: true）まで待ちます。
2. 容量またはクォータのエラーを解決する：ステップ 3 で ZONE_RESOURCE_POOL_EXHAUSTED_WITH_DETAILS または QUOTA_EXCEEDED が表示された場合、アップグレードをロールバックしても不足は解消されません。Issue: Node pool creation fails due to insufficient resourcesと、GKE の TPU のトラブルシューティングの「TPU リクエストを満たすのに十分なクォータがありません」および「TPU リクエストを満たすのに十分な TPU リソースがありません」のセクションに従ってください。
3. 進行中のノードプールのアップグレードをキャンセルする：ユーザーが実行中のアップグレードを停止したい場合は、ノードプールのアップグレードをキャンセルするに従ってください。動的スライシングのノードプールでは、アップグレードに必要なサージ設定と、アップグレード前にアクティブなスーパースライスを削除する方法について、ノードプールをアップグレードするも確認してください。
4. キャンセル、失敗、または未完了のノードプールのアップグレードを再開またはロールバックする：
   • クラスタのコントロールプレーンまたはノードプールを手動でアップグレードするの「ノードプールのアップグレードを再開する」または「ノードプールのアップグレードをロールバックする」のセクションに従ってください。そこに記載されているように、ロールバックが適用されるのは、進行中のアップグレードがキャンセルされた場合、アップグレードに失敗した場合、またはメンテナンス期間のタイムアウトによりアップグレードが未完了の場合です（正常にアップグレードされたノードプールはロールバックできません）。または、キャンセルまたは失敗したアップグレードの一部が完了している場合は、アップグレードを再開できます。
   • その後、MIG が安定しているかどうかを確認するに従って、MIG が安定していることを確認してください。
5. 原因不明の MIG の不安定状態をエスカレーションする：ノードプールのアップグレード、修復オペレーション、容量またはクォータのエラーのいずれも、{mig_name} が不安定なままである理由として説明できない場合は、サポートを受けるに従って、ユーザーに Cloud Customer Care への問い合わせを案内してください。
6. ノードプールとスライスの復旧を確認する：インスタンスグループが安定した（status.isStable: true）後、カスタムスケジューラで動的スライシングを使用するの「Slice カスタムリソースのステータスをモニタリングする」および「Slice カスタムリソースを作成する」のセクションに従って、Slice が ACTIVE 状態になることを確認してください。MIG が安定した後も Slice が SliceCreationFailed のままの場合は、「Slice カスタムリソースを作成する」に記載されている再試行アノテーションが Slice に設定されているか確認してください。