gke-ai-troubleshooting-tpu-partition-overlap

パーティションの重複による TPU スライス作成の失敗をトラブルシューティングする

動的スライスは、ほかに文書化されている原因に加えて、そのノードが別のスライスですでに使用されている場合、ステータスの理由が SliceCreationFailed となり、作成に失敗します。このスキルでは、失敗を確認し、ほかに文書化されている原因を除外して、同じノードを使用するスライスを特定し、GKE を通じて修正を行います。

Attribution

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

前提条件

• ツール：
  • 認証とプロジェクト選択を含む gcloud のインストールと初期化については、 始める前にに従ってください。
  • kubectl と必要なプラグインのインストールについては、kubectl のインストール および 必要なプラグインのインストールに従ってください。
• Cloud Billing とプロジェクトの構成：プロジェクトに有効な Cloud Billing アカウントがあることを確認してください。始める前にに従って gcloud を初期化し、Google Kubernetes Engine API (container.googleapis.com) を有効にしてください。Cloud Monitoring API (monitoring.googleapis.com) が有効であることを確認し、kubectl 用のクラスタ情報の保存に従って kubectl のクラスタ認証情報を構成してください。
• 必要な IAM ロール：
  • Kubernetes Engine Viewer (roles/container.viewer)
  • Monitoring Viewer (roles/monitoring.viewer)
• ドキュメント：
  • カスタムスケジューラを使用した動的スライシング （セクション：「始める前に」、「ノードプールをブロックまたはサブブロックに属するように設定する」、「ノードとパーティションのステータスを確認する」、 「Slice カスタムリソースを作成する」、「Slice カスタムリソースのステータスを監視する」、「スライスを削除する」）
  • kubectl のクラスタアクセスを構成する （セクション：「kubectl のインストール」、「必要なプラグインのインストール」、「kubectl 用のクラスタ情報の保存」）
  • Slice （セクション：「Slice のステータス」、「Slice の仕様」）
  • Kueue と TAS を使用して動的スライスをスケジュールする （セクション：「ノードプールをブロックまたはサブブロックに属するように設定する」、 「Kueue と TAS を使用して動的スライスを作成する」、「パーティションの健全性選択を定義する」、 「スライスの再利用によってワークロードのスケジューリングを最適化する」、「Slice の再利用を有効にする」、 「ワークロードごとにスライスの削除を適用する」、「スライスのステータスを監視する」、 「スライスのメトリクスを監視する」、「クリーンアップ」）
  • GKE システムメトリクス （セクション：「Kubernetes メトリクス」）
  • 監視対象のリソースタイプ （セクション：「k8s_node_pool」）
  • GKE の動的スライシングについて （セクション：「動的スライシングの構成」）
  • サポートを受ける （セクション：「サポートに問い合わせる前に」、「効率的なサポートを受けるための推奨事項」）

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

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

---

診断ワークフロー

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

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

• {project_id}：Google Cloud プロジェクト ID
• {cluster_name}：GKE クラスタ名
• {location}：クラスタのリージョンまたはゾーン
• {slice_name}：作成に失敗した Slice カスタムリソースの名前
• {node_pool_name}：{slice_name} のパーティションを支える TPU ノードプールの名前（複数ある場合はその名前）。判明している場合に記録します。ユーザーが {node_pool_name} を把握していない場合は、ステップ 1 の後に、ステップ 3 の Cloud Monitoring クエリを {partition_ids} 内のパーティション ID に対して実行し、 k8s_node_pool のモニタリング対象リソースにある node_pool_name ラベルを確認します。
• {issue_time}：判明している場合は、RFC3339 形式の UTC インシデント発生時刻を記録します。ユーザーが {issue_time} を把握していない場合は、ステップ 1 で確認する Ready 条件の Last Transition Time （lastTransitionTime。 Slice status における「ステータスが最後に変更された時刻のタイムスタンプ」）を使用します。デフォルトでは、{issue_time} を中心とした 60 分間を対象に Cloud Monitoring をクエリします。

---

ステップ 1：SliceCreationFailed ステータスを確認する [Low Risk]

{slice_name} を説明するには、 Slice カスタムリソースのステータスを監視する の手順に従います。

• Status > Conditions で、Ready 条件の Reason が SliceCreationFailed であることを確認し、Last Transition Time を記録します（必要に応じて {issue_time} として使用します）。
• Spec > Partition Ids にある ID を {partition_ids} として記録し、Topology、および {slice_name} に設定されている Labels と Annotations を記録します。
• Ready の理由が SliceCreationFailed でない場合、このスキルは適用されません。各理由の意味については Slice status を参照し、 gke-ai-troubleshooting-tpu-dynamic-slices-monitoring に引き継ぎます。

---

ステップ 2：ほかに文書化されている原因を除外する [Low Risk]

スライスのカスタムリソースを作成する によると、次の場合もスライスの作成は SliceCreationFailed で失敗します。

• 選択したノードが存在しません。
• トポロジがパーティション数と一致していません。動的サブスライスには、パーティション ID が正確に 1 つ記載されます。動的スーパー スライスには、(A × B × C) / 64 個のパーティション ID が記載されます。

いずれかの原因に該当する場合は、 gke-ai-troubleshooting-tpu-dynamic-slices-monitoring に引き継いでください。

該当しない場合は、{node_pool_name} で ノードとパーティションのステータスを確認する 手順に従ってください。

• ノードが存在し、{partition_ids} の各 ID が付与されていることを確認します。
• {partition_ids} が付与されたノードについて、cloud.google.com/gke-tpu-partition-.*-id ラベルから、すべての形状（4x4x4、2x4x4、2x2x4、2x2x2、2x2x1）のすべてのパーティション ID を記録します。 動的スライス構成 によると、動的サブスライスでは、同じ物理ノードプール上で 4x4x4 サブブロックをより小さなトポロジに分割するため、異なる形状のパーティションが同じノードを共有します。
• 各パーティションの cloud.google.com/gke-tpu-partition-.*-state ラベルを読み取ります。 ノードとパーティションのステータスを確認する および パーティションのヘルス選択を定義する に従い、HEALTHY パーティションと、DEGRADED 状態の 4x4x4 パーティション（「動的スライスの形成には引き続き使用可能」、「小さいトポロジには degraded 状態がない」）を使用可能として数えます。UNHEALTHY（「スライスの形成には使用できない」）、UNSET、INCOMPLETE のパーティションは使用できません。要求されたパーティションが UNHEALTHY、UNSET、または INCOMPLETE の場合は、どのスライスも使用していないノードを持つ使用可能なパーティションを提案するか（ステップ 4、項目 2）、gke-ai-troubleshooting-tpu-dynamic-slices-monitoring に引き継ぐか、Cloud カスタマーケアにエスカレーションしてください（ステップ 4、項目 4）。

---

ステップ 3：同じノードを使用しているスライスを見つける [Low Risk]

Slice カスタムリソースの作成によると、カスタムリソース上のノードが別のスライスで使用されている場合、スライスの作成は SliceCreationFailed で失敗します。異なる形状のパーティションは同じサブブロック上でノードを共有するため（Dynamic slicing configurationsを参照）、ステップ 2 で {slice_name} のノードに記録されたパーティション ID（形状を問わない）のいずれかをリストに含む別のスライスは、{slice_name} と競合します。

1. クラスター内の Slice カスタムリソースを一覧表示し（スライスの削除を参照）、Slice カスタムリソースのステータスをモニタリングするの手順に従って各リソースを記述し、Spec > Partition Ids、Metadata > Labels、および Status > Conditions（Ready の理由）を確認します。
   • Spec > Partition Ids に、ステップ 2 で {slice_name} のノードに記録されたパーティション ID（{partition_ids} にある正確な ID、または同じノード上の別の形状のパーティション ID）のいずれかが含まれる {slice_name} 以外のスライスは、競合しているものとして扱います。その名前、Ready の理由（ACTIVE など）、および Kueue が管理しているかどうか（ステップ 4、項目 1）を記録します。
2. Cloud Monitoring でパーティションとスライスの関連付け（{issue_time} 前後を含む）を確認するには、スライスのメトリクスをモニタリングするに記載されている kubernetes.io/accelerator/partition/state メトリクスをクエリします。Kubernetes metricsによると、このメトリクスは「パーティションの状態が検出された場合は 1、それ以外の場合は 0」であり、ラベルには partition_id、slice_id（「関連付けられたスライスの ID」）、state（「パーティションの健全性（例：HEALTHY、UNHEALTHY）」）が含まれます。ステップ 2 で {slice_name} のノードに記録された各 {partition_id} に対してクエリを実行します。

kubernetes_io:accelerator_partition_state{
  monitored_resource="k8s_node_pool",
  cluster_name="{cluster_name}",
  partition_id="{partition_id}"
}

• 値が 1 の時系列のみを確認します（ノードとパーティションのステータスを確認するによると、state="HEALTHY" はパーティションが健全で機能していることを意味します）。
• Kubernetes metricsでは slice_id を「関連付けられたスライスの ID」とのみ定義しているため、slice_id だけで判断せず、クラスター内の Slice カスタムリソースを確認して、競合しているスライスを必ず特定します。スライスの削除に示されているように Slice カスタムリソースを一覧表示し、Slice カスタムリソースのステータスをモニタリングするの手順に従って各リソースを記述し、どのスライスの Spec > Partition Ids にそのパーティション ID（またはステップ 2 で確認した同じノード上の別形状のパーティション ID）が含まれるかを確認します。

3. ステップ 3 の結果に基づく次の手順：
   • 現在、別のスライスがノードを使用しています：ステップ 4 に進みます。
   • 現在、ノードを使用している別のスライスはありませんが、メトリクス（値 1）に {issue_time} 前後の関連付けられた slice_id が示されていました：競合はすでに解消している可能性があります。ステップ 4 の項目 1（{slice_name} を再作成または再試行するため）に進み、その後ステップ 4 の項目 4 に進みます。
   • 現在の Slice カスタムリソースにも {issue_time} 前後のメトリクスにも、別のスライスが示されていません：ノードの重複は確認できていません。gke-ai-troubleshooting-tpu-dynamic-slices-monitoring に引き継ぐか、Cloud Customer Care にエスカレーションします（ステップ 4、項目 4）。

---

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

ガードレール：

• ノードを空けるために、もう一方のスライスを決して削除または変更したり、そのワークロードを停止したりしないでください。Slice カスタムリソースを削除すると、そのスライスの解体が開始されます（DEACTIVATING。詳細は Slice カスタムリソースのステータスを監視する を参照してください）。そのスライスを解放するタイミングは、所有者が決定します。
• Kueue によって作成された Slice カスタムリソースを決して手動で変更または削除しないでください。 ノードプールをブロックまたはサブブロックに所属させる にあるとおり、「Kueue によって作成された Slice カスタムリソースは手動で変更しないでください」。
• Compute Engine を介して GKE 管理のインスタンスグループや VM を直接決して変更しないでください。また、パーティションを空けるためにノードプールを削除しないでください。ノードプールとスライスは GKE を通じて管理してください。

まず、Kueue が {slice_name} または競合しているスライスを管理しているか確認してください。

• スライスのステータスを監視する にあるとおり、スライスが作成されたとき、またはワークロードでアクティブに使用されているとき、スライスコントローラーは kueue.gke.io/tpu-slice-used-by-namespace および kueue.gke.io/tpu-slice-used-by-workload ラベルを付加します。
• スライスの再利用によるワークロードスケジューリングの最適化 および Slice の再利用を有効にする にあるとおり、スライスの再利用が有効な場合、「ジョブの終了時に Kueue はスライスを削除せず、アイドル状態としてマークします」。また、「再利用可能なスライスには s-<topology> プレフィックスを付けた動的な名前が付与されるため、特定のワークロード名との関連付けがなくなります」。

次に、該当するオプションを適用してください。

1. 競合するスライスがノードを解放するまで待ち、再試行します：
   • 競合するスライスを Kueue が管理している場合（kueue.gke.io/... ラベルが付いているか、名前のプレフィックスが s-<topology> の場合）：Slice カスタムリソースを直接削除するよう提案しないでください。ワークロードの所有者にクリーンアップを案内してください（JobSet を削除すると、Kueue が関連する Slice カスタムリソースを削除します）。また、スライスの再利用によってジョブの終了後もアイドル状態の s-<topology> スライスが割り当てられたままになる場合は、ワークロードごとにスライスの削除を強制するよう案内してください（kueue.gke.io/tpu-enforce-slice-deletion: "true"）。
   • カスタムスケジューラーまたはユーザーが競合するスライスを直接作成した場合：所有者は、スライスを削除するの説明に従って、作業が完了したら削除できます。
   • {slice_name} の再試行方法：{slice_name} の Metadata > Annotations に、すでに slice.gke.io/retry-on-failure: "true" が設定されているか確認します。Slice カスタムリソースを作成するによると、このアノテーションを付けて Slice カスタムリソースを作成した場合、「SliceCreationFailed ステータスの理由によりスライスが作成されないと、コントローラーはスライスが正常に形成されるまで再試行します」。ドキュメントでは、Slice カスタムリソースの作成時に Slice マニフェストで slice.gke.io/retry-on-failure: "true" を設定する方法のみが示されており、すでに SliceCreationFailed になっている既存のスライスにこのアノテーションを追加すると再試行が始まるとは記載されていません。そのため、{slice_name} が Kueue によって作成されたものではなく、このアノテーションもない場合は、スライスを削除するの手順に従って {slice_name} を削除し、Slice カスタムリソースを作成するの手順に従って、マニフェストに slice.gke.io/retry-on-failure: "true" を設定して再作成するようユーザーに伝えてください。
2. 他のスライスがノードを使用していない、利用可能なパーティションを使用します：ユーザーが（Kueue を介さずに）Slice カスタムリソースを直接管理しており、待機できない場合は、ノードとパーティションのステータスを確認するおよびSlice カスタムリソースを作成するよう案内してください。これにより、他のスライスが使用していないノードの利用可能なパーティション（HEALTHY パーティション、または DEGRADED の 4x4x4 パーティション）を選択し、それらを使って Slice カスタムリソースを作成できます。
3. Slice カスタムリソースを直接作成する代わりに、Kueue と TAS で動的スライスをスケジュールします：ノードプールをブロックまたはサブブロックに属するよう設定するおよびKueue と TAS で動的スライスを作成するによると、Slice カスタムリソースを直接作成する代わりに、チームは Kueue と Topology Aware Scheduling (TAS) を使用して GKE ワークロードをスケジュールできます。この場合、「Kueue は Slice カスタムリソースの作成と削除を自動的に処理」し、スライスがアクティブになった後にワークロードを受け入れます。
4. 確認またはエスカレーションします：Slice カスタムリソースのステータスをモニタリングするに従ってステップ 1 を繰り返します。
   • ACTIVE：スライスは完全に形成され、正常で、ワークロードを実行できる状態です。
   • ACTIVE_DEGRADED：スライスは形成されており、ワークロードを実行できますが、パフォーマンスに影響が出る可能性があります。
   • 他のスライスがノードを使用していない状態でも SliceCreationFailed のまま、または FAILED：gke-ai-troubleshooting-tpu-dynamic-slices-monitoring に引き継ぐか、サポートに問い合わせる前におよび効率的なサポートを受けるための推奨事項に従って Cloud カスタマーケアに連絡するようユーザーに案内してください。