gke-ai-troubleshooting-tpu-reservation-stockout

リークしたノードプール容量に起因する GKE TPU 予約の在庫切れをトラブルシューティングする

このスキルを使用して、特定の Compute Engine TPU 予約を対象としているにもかかわらず、GCE_STOCKOUT、ZONE_RESOURCE_POOL_EXHAUSTED、ZONE_RESOURCE_POOL_EXHAUSTED_WITH_DETAILS で失敗する（または容量不足によりキューに入る）GKE TPU ノードプールの作成またはスケールアップの失敗を診断し、解決します。

既存の TPU ノードプールでノードの自動修復が無効になっている場合、GKE はノードが NotReady になっても修復しません。ノードの VM がまだ実行中である間、それらは予約のスロットを引き続き消費します（inUseCount は、予約を消費する実行中のインスタンスの数です）。 予約の空き状況を確保するによると、ノードプールの作成時に予約に十分な TPU チップの空きが必要です。また、マルチホスト TPU スライスのノードプールによると、GKE がスライス内の 1 つのノードをデプロイできない場合、TPU スライスのノードプール内のノードはどれもデプロイされません。予約内の空きスロット数（specificReservation.count - specificReservation.inUseCount。予約で消費可能なインスタンスを参照）が、新しい TPU ノードプールに必要なノード数を下回ると、作成は GCE_STOCKOUT または ZONE_RESOURCE_POOL_EXHAUSTED で失敗するか、容量不足によりキューに入ります。

帰属情報

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

前提条件

• 必須の IAM ロール：
  • ログ閲覧者（roles/logging.viewer）：Cloud Logging で Cloud Audit Logs をクエリします。
  • Monitoring 閲覧者（roles/monitoring.viewer）：Cloud Monitoring で GKE ノードの準備状態メトリクスをクエリします。
  • Kubernetes Engine 閲覧者（roles/container.viewer）：GKE ノードプール（management.autoRepair）、クラスタの操作、ノードの状態を調査します。
  • Compute 閲覧者（roles/compute.viewer）：Compute Engine の予約の使用状況（specificReservation.inUseCount と specificReservation.count の比較）、使用中のインスタンス、VM ラベルを調査します（共有予約を使用する場合は、予約のオーナープロジェクト内も含みます）。
  • 修復の場合（[High Risk] の手順）：Kubernetes Engine クラスタ管理者（roles/container.clusterAdmin）
• API の有効化と課金：
  • 対象プロジェクトに有効な Google Cloud 請求先アカウントが紐付けられていることを確認します：gcloud billing projects describe {project_id}。
  • 必要な API を有効にします：container.googleapis.com、compute.googleapis.com、logging.googleapis.com、monitoring.googleapis.com。
• CLI と認証の設定：
  • Google Cloud SDK（gcloud）と kubectl をインストールします： https://cloud.google.com/sdk/docs/install.
• クラスタモード：このスキルは Standard クラスタに適用されます。Autopilot クラスタでは常にノードが自動修復され、これを無効にすることはできません（Autopilot と Standard の設定を参照）。
• 参考ドキュメント：
  • ノードの自動修復 （セクション：「Autopilot と Standard の設定」、「修復条件」、「ノードの修復プロセス」、「Standard ノードプールでノードの自動修復が有効になっていることを確認する」、「TPU スライスノードのノード自動修復」、「既存の Standard ノードプールで自動修復を有効にする」、「最近の自動修復イベントに関する情報を取得する」）
  • GKE Standard ノードプールのトラブルシューティング （セクション：「問題：リソース不足によりノードプールの作成に失敗する」）
  • GKE の TPU のトラブルシューティング （セクション：「GKE が容量の問題を処理する方法」、「TPU リクエストを満たすための TPU リソースが不足している」）
  • GKE の TPU について （セクション：「マルチホスト TPU スライスノードプール」）
  • 予約済みゾーンリソースの使用 （セクション：「特定の共有予約の使用」）
  • 予約について （セクション：「予約の仕組み」）
  • 予約または将来の予約リクエストを表示する （セクション：「制限事項」、「予約を表示する」、「予約内で使用可能なインスタンス」、「予約を使用しているインスタンスのリストを表示する」）
  • ラベルを使用してリソースを整理する （セクション：「ラベルを表示する」）
  • クラスタとノードプールのラベルを作成して管理する （セクション：「自動的に適用されるラベル」）
  • GKE Standard に TPU ワークロードをデプロイする （セクション：「予約の利用可能性を確認する」、「TPU ノードとノードプールの健全性メトリクスをモニタリングする」、「TPU スライスノードの自動修復を設定する」）
  • ノードプールを追加して管理する （セクション：「ノードプールを削除する」）

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

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

---

診断ワークフロー

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

ユーザーのプロンプトまたはクラスタのコンテキストから、次の環境パラメーターを特定します。

• {project_id}、{cluster_name}、{location}、{failing_nodepool_name}、 {reservation_name}、{reservation_project_id}（{reservation_name} を所有するプロジェクト。単一プロジェクトの予約では既定で {project_id} となり、共有予約では所有者プロジェクトとなります。詳しくは特定の共有予約を使用するをご覧ください）、 {zone}（予約のゾーン）、および {issue_time}。
• 時間枠：既定では、60 分間の時間枠 [{issue_time} - 30m, {issue_time} + 30m]（{start_time} から {end_time}）をクエリします。

---

ステップ 1：在庫切れエラーと予約の使用状況を確認する [Low Risk]

1. Cloud Audit Logs と GKE のオペレーションで、在庫切れまたは容量不足のエラーを確認する：
   • 問題：リソース不足によりノードプールの作成に失敗するにあるクエリを [{start_time}, {end_time}] の期間に実行し、ZONE_RESOURCE_POOL_EXHAUSTED や ZONE_RESOURCE_POOL_EXHAUSTED_WITH_DETAILS など、記載されているエラーメッセージを探します。
   • TPU リクエストを満たすための TPU リソースが不足しているにあるように、TPU エラーに GCE_STOCKOUT が含まれることもあります。
   • GKE における容量問題への対処方法にあるように、GKE は TPU ノードプールの作成リクエストをすぐに失敗させず、キューに入れる場合があります。その場合、GCE_STOCKOUT の代わりに ... cannot be created ... due to lack of capacity というメッセージが表示されます。gcloud container operations list （--filter="operationType=CREATE_NODE_POOL"）を使用して、ノードプールの作成オペレーションを一覧表示します。
2. Compute Engine の予約使用状況を確認する：
   • 制限事項にあるように、共有予約は作成されたオーナープロジェクト（{reservation_project_id}）でクエリします。
   • 予約の表示のセクションに従い、gcloud compute reservations describe {reservation_name} --zone={zone} --project={reservation_project_id} または gcloud compute reservations list --project={reservation_project_id} を実行し、 specificReservation.inUseCount と specificReservation.count を比較します。

結果の解釈

• 既存のどの VM とノードプールが予約済み容量を保持しているかを特定するまで、ノードプールの削除を提案しないでください（ステップ 2）。
• 在庫切れを確認：予約の利用可能性を確保するおよびマルチホスト TPU スライスのノードプールにあるように、GKE がマルチホストスライス内の 1 つのノードでもデプロイできない場合、そのスライスのノードは 1 つもデプロイされません。在庫切れまたは容量不足のメッセージがあり、空きスロット数（specificReservation.count - specificReservation.inUseCount。予約内で利用可能なインスタンスを参照）が {failing_nodepool_name} に必要なノード数を下回る場合は、ステップ 2 に進みます。

---

ステップ 2：予約を保持している VM とノードプールを特定します [Low Risk]

1. {reservation_name} を消費している VM を確認します：
   • 予約の仕組みによると、特定の対象に割り当てられた予約は、予約のプロジェクト（{reservation_project_id}）内の VM、または共有予約の場合は、その予約が共有されている任意のプロジェクト内の VM が使用できます。
   • 予約を消費しているインスタンスの一覧を表示するの手順に従って、{reservation_name} を使用している VM を一覧表示します。
   • ラベルを表示するの手順に従って各 VM のラベルを確認し、自動的に適用されるラベルにある GKE ラベル（goog-k8s-cluster-name、goog-k8s-cluster-location、goog-k8s-node-pool-name）を確認して、各 VM のクラスターとノードプールを特定します。
2. {cluster_name} のノードの準備状況を確認します：
   • TPU ノードとノードプールのヘルス指標をモニタリングするで説明されている Cloud Monitoring 指標 kubernetes_io:node_status_condition（monitored_resource="k8s_node"、cluster_name="{cluster_name}"、condition="Ready"）をクエリします。status ラベルの値は True、False、または Unknown（先頭大文字）です。Ready 条件が False または Unknown のノードを見つけるには、status!="True" を使用します。
   • kubectl get nodes -l cloud.google.com/gke-tpu-accelerator -L cloud.google.com/gke-nodepool を実行し、TPU ノードとそのノードプールのラベルを一覧表示します。
3. 障害が発生しているノードプールを除外します：{failing_nodepool_name} は異常なノードプールの一覧に含めないでください。容量を確保できなかったノードプールであり、容量を保持しているノードプールではありません。

結果の解釈

• {cluster_name} の外部にある VM：{reservation_name} を消費している VM の一部が {cluster_name} のノードではない場合（たとえば、ラベルに別の GKE クラスターが表示されている場合や、GKE ラベルのない Compute Engine VM の場合）、どの VM または他のクラスターが予約枠を保持しているかをユーザーに伝えます。
• 一覧表示された VM の数が specificReservation.inUseCount より少ない場合：予約を消費しているインスタンスの一覧を表示するによると、一覧には 1 つのプロジェクト内の VM のみが含まれます。一覧表示された VM の数が specificReservation.inUseCount より少ない場合は、{reservation_name} を共有している他のプロジェクト内の VM が残りの予約枠を消費していることをユーザーに伝えます。
• {cluster_name} に異常なノードプール（{leaking_nodepool_name}）がある場合：{reservation_name} を消費している VM が、{cluster_name} 内の既存の NotReady ノードプール（{leaking_nodepool_name}）に属している場合は、ステップ 3 に進みます。
• 予約は正常（リークの可能性を排除）：予約枠が正常に使用中のノードプールによって保持されている場合、リークはありません。正常なノードプールが予約枠を保持しているため、{failing_nodepool_name} が使用できる空き枠が不足していることを説明します。これらの正常なノードプールを削除または再起動しないようユーザーに伝え、TPU リクエストを満たすための TPU リソースが不足しているにある消費オプションを案内します。

---

ステップ 3：予約を消費しているノードプールでノードの自動修復を確認する [Low Risk]

{leaking_nodepool_name} について、Standard ノードプールでノードの自動修復が有効になっていることを確認するに従います。

• 自動修復が無効（management.autoRepair: false）：GKE は {leaking_nodepool_name} の NotReady ノードを修復しません。実行中の VM は {reservation_name} の specificReservation.inUseCount にカウントされ続けるため、{failing_nodepool_name} は予約済み容量を取得できません。ステップ 4 に進みます。
• 自動修復が有効（management.autoRepair: true）なのに、ノードが引き続き NotReady：
  • 修復条件に従い、ノードが NotReady になってから修復のしきい値（約 10 分）を超えているか確認します。
  • TPU スライスノードの自動修復を構成するおよび最近の自動修復イベントに関する情報を取得するに従い、オペレーション履歴で修復ステータスと失敗理由を確認します。

---

ステップ 4：予約容量を回復する、または解放する [High Risk]

ガードレール：Compute Engine を通じて、GKE が管理するインスタンスグループや VM を直接変更しないでください。ノードプールは GKE を通じて管理してください。アクティブなジョブを実行している正常なノードプールは削除しないでください。

1. ユーザーが {leaking_nodepool_name} をその場で修復したい場合は、ノードの自動修復を有効にします（{failing_nodepool_name} のスロットは解放されません）：
   • ノード修復プロセスに従い、GKE は異常なノードをドレインして再作成します。
   • TPU スライスノードのノード自動修復およびTPU スライスノードの自動修復を構成するに従い、TPU スライス内のノードに修復が必要な場合、GKE はマルチホスト TPU スライスノードプール全体を再作成します。再作成された VM も引き続き {reservation_name} を消費するため、specificReservation.inUseCount は減少しません。自動修復を有効にすると {leaking_nodepool_name} のノードは再び正常になりますが、{failing_nodepool_name} は引き続きスロットを取得できません。
   • {leaking_nodepool_name} の自動修復を有効にするには、ユーザーに既存の Standard ノードプールで自動修復を有効にするを案内します。
2. {leaking_nodepool_name} が古いノードプールである場合、またはユーザーが {failing_nodepool_name} のためにそのスロットを解放したい場合は、GKE を通じて削除します：ユーザーにノードプールを削除するを案内し、{leaking_nodepool_name} を削除します。これにより、その VM が使用している予約済みスロットが解放されます。
3. ユーザーが {leaking_nodepool_name} を削除した後、十分な予約スロットが空いていることを確認します：予約を表示するに従い、gcloud compute reservations describe {reservation_name} --zone={zone} --project={reservation_project_id} を実行します。specificReservation.inUseCount が減少し、空きスロット（specificReservation.count - specificReservation.inUseCount）が、{failing_nodepool_name} を再試行する前に必要なノード数以上になっていることを確認します。