gke-tpu-dynamic-slices-monitoring

GKE TPU 動的スライスのモニタリングと管理

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

前提条件

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

診断ワークフロー

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

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

• プロジェクト ID：{project_id}（例：my-gcp-project）
• クラスター名：{cluster_name}（例：tpu-cluster）
• リージョン／ゾーン：{location}（例：us-central1-a）
• スライス名：{slice_name}（例：test-slice）
• 問題発生時刻：{timestamp}（省略可。デフォルトでは直近 30 分の時間範囲 [T - 30m] から [T + 30m] を使用します）

---

ステップ 1：スライスのカスタムリソースを記述する［低リスク］

スライスの検査、トラブルシューティング、または状態確認を求められた場合は、利用可能なクラスターのツールを使用して 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	スライスを解体しています（ユーザーによる削除、または重大なシステム障害によって開始）。	解体が完了するまで待つか、停止している場合はファイナライザーをパッチします。
: : : :
: : : :
: : : :
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-
   

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