gke-ai-troubleshooting-tpu-dynamic-slices-monitoring

GKE TPU Dynamic Slices のモニタリングと管理

TPU Slice カスタムリソースのステータスを監視し、プロビジョニングの失敗をトラブルシューティングし、ダイナミックスライス上のワークロードマニフェストを検証して、クリーンアップを実行します。

帰属情報

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

前提条件

• プロジェクトで Cloud Logging が有効になっていること。
• GKE クラスターにアクセスできるよう、kubectl と gcloud CLI が構成されていること。

診断ワークフロー

ステップ 0：コンテキストの取得と時間範囲の定義

クラスターのツール、または次のパラメーターを使用して、プロジェクト、クラスター、スライスのコンテキストを取得します。

• Project ID：{project_id}（例：my-gcp-project）
• Cluster Name：{cluster_name}（例：tpu-cluster）
• Region/Zone：{location}（例：us-central1-a）
• Slice Name：{slice_name}（例：test-slice）
• Issue Time：{timestamp}（任意。デフォルトでは直近 30 分の時間範囲 [T - 30m] から [T + 30m] を使用します）

---

ステップ 1：Slice カスタムリソースの詳細を確認する［低リスク］

スライスの調査、トラブルシューティング、またはステータス確認を依頼された場合は、利用可能なクラスターのツールを使用して、直ちに kubectl describe slice {slice_name} を実行し、調査します。出力された Status.Conditions を以下の条件テーブルに照らして解析し、正確な状態を診断して具体的な推奨事項を提示します。

• コマンド：

  kubectl describe slice {slice_name}
  

状態と理由の分析

Status.Conditions（特に Type: Ready とその Reason および Status）を分析します。

ライフサイクルの状態／理由	意味	推奨される対応
SliceNotCreated	GKE Slice Controller がスライスを初期化し、リソースを確認しています。	数分待ってから、スライスのステータスを再確認してください。
SliceCreationFailed	前提条件の検証に失敗しました（例：選択したノードが存在しない、ノードがすでに別のスライスで使用されている、トポロジがパーティション数と一致しない）。	選択したノードが存在し、割り当てられておらず、トポロジがパーティション数と一致していることを確認してください。
ACTIVATING	GKE が TPU スライスの形成とプロビジョニングを進めています。	ノードのプロビジョニングを監視してください。
ACTIVE	TPU スライスの形成が正常に完了し、ワークロードを実行できる状態です。	ワークロードのデプロイまたは確認に進んでください。
ACTIVE_DEGRADED	スライスは使用できますが、1 つ以上のサブブロックが低下しています。	相互接続またはデバイスのエラーがないか、ワークロードのログを監視してください。障害が発生したノード VM を確認してください。
FAILED	GKE が TPU スライスを形成できませんでした（例：選択したノードが同じ予約ブロックに属していない）。	選択したすべてのノードが同じ予約ブロックに属していることを確認してください。
DEACTIVATING	スライスを解体しています（ユーザーによる削除、または重大なシステム障害によって発生）。	解体が完了するまで待つか、停止している場合は finalizer にパッチを適用してください。
INCOMPLETE	Slice CR がクラスターから削除される前の最終フェーズです。	対応は不要です。リソースはまもなく削除されます。

プロビジョニング失敗のトラブルシューティングチェックリスト

スライスの作成またはプロビジョニングに失敗した場合（SliceCreationFailed または FAILED）、次の確認手順を実施します。

1. ノードの存在と割り当ての確認：選択した TPU ノードがクラスターに存在し、別のスライスにすでに割り当てられていないことを確認します（kubectl get nodes -l cloud.google.com/gke-tpu-slice、kubectl get slice -A）。
2. トポロジーの整合性：パーティション数が要求されたトポロジーの次元と一致していることを確認します（例：トポロジー 2x2 の場合、4 ノードが必要です）。
3. 予約ブロックの整合性確認：選択したすべての TPU ノードが同じ予約と予約ブロックに属していることを確認します。

---

ステップ 2：ワークロード仕様の確認［低リスク］

ワークロードマニフェストが、動的スライスを対象とするよう正しく設定されていることを確認します。

1. 単一スライスのワークロード要件

Pod テンプレートに次のアノテーションとセレクターが含まれていることを確認します。

• アノテーション：
  • cloud.google.com/gke-tpu-slice-topology: "{topology}"（例： "4x4x4"）
• NodeSelector：
  • cloud.google.com/gke-tpu-topology: "{topology}"（例："4x4x4"）
  • cloud.google.com/gke-tpu-accelerator: "{accelerator_type}"（例： "tpu7x"）
  • cloud.google.com/gke-tpu-slice: "{slice_name}"（例："test-slice"）

2. マルチスライス（JobSet）ワークロード要件

マルチスライスの JobSet をデプロイする場合は、次を確認します。

• JobSet アノテーション：
  • alpha.jobset.sigs.k8s.io/exclusive-topology: cloud.google.com/gke-tpu-slice
• Pod テンプレートのアノテーション：
  • cloud.google.com/gke-tpu-slice-topology: "{topology}"
• Pod テンプレートの NodeSelector：
  • cloud.google.com/gke-tpu-topology: "{topology}"
  • cloud.google.com/gke-tpu-accelerator: "{accelerator_type}"
  • 注：JobSet がスライスの割り当てを自動的に処理するため、NodeSelector に cloud.google.com/gke-tpu-slice を手動で指定しないでください。

---

解決と管理のワークフロー

解決策 1：停止したスライスを強制削除する［高リスク］

スライスが DEACTIVATING の状態で停止している場合や、ファイナライザーの停止により削除が無期限にハングしている場合：

1. 原因の特定：スライスリソースのファイナライザー（metadata.finalizers）が、Kubernetes によるリソース削除の完了を妨げていることを説明します。

2. 解決策の提案：JSON パッチ操作を使用して、メタデータパス（/metadata/finalizers）からファイナライザーを削除する方法を提案します。

   kubectl patch slice {slice_name} --type json -p='[{"op": "remove", "path": "/metadata/finalizers"}]'
   

3. 警告の提示：ファイナライザーを削除すると標準のコントローラーによる解体処理が迂回され、基盤となる VM、ネットワーク、アクセラレーターのリソースがクリーンアップされずに残ったり、孤立したりする可能性があることを、ユーザーに明示的に警告します。

4. 重大な安全上の必須事項：応答では、必ずユーザーに確認を明示的に求め（例：「JSON パッチで /metadata/finalizers のファイナライザーを削除する操作は高リスクであり、リソースが孤立する可能性があります。スライス {slice_name} にこのパッチを適用することを確認しますか？」）、パッチを適用または実行する前に、ユーザーの確認を待ちます。

---

解決策 2：スライスコントローラーを無効にしてクリーンアップする［高リスク］

動的スライスを無効にする必要がある場合：

1. 既存のスライスを確認する：

   kubectl get slice -A
   

   コントローラーを無効にする前に、すべてのスライスが削除されていることを確認します。

2. gcloud でスライスコントローラーを無効にする：

   gcloud container clusters update {cluster_name} \
       --location={location} \
       --no-enable-slice-controller
   

3. Slice CRD を削除する：

   kubectl delete crd slices.accelerator.gke.io
   

4. ノードラベルをクリーンアップする：クラスター内のすべてのノードから GKE TPU Slice ラベルを削除します：

   kubectl label nodes --all cloud.google.com/gke-tpu-slice- cloud.google.com/gke-tpu-slice-topology-
   

• 安全ルール：無効化や破壊的なクリーンアップ手順を実行する前に、実行するコマンドを正確に提示し、確認を得てください。