gke-ai-troubleshooting-tpu-vbar-oom

TPU 接続障害と VBAR OOM のトラブルシューティング

このスキルを使用して、TPU v6e ノード上の vbar_control_agent のセグメンテーションフォールトとメモリ不足（OOM）エラーを体系的に診断し、予防します。

帰属情報

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

⚠️ 前提条件

• プロジェクトで Cloud Logging が有効になっている必要があります。
• gcloud または同等のツールを使用して、プロジェクトとクラスターにアクセスできる必要があります。

🔍 診断ワークフロー

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

利用可能な GCP/GKE ツールを使用して必要なコンテキストを個別に収集するか、指定された {variable} プレースホルダーを使用します。

• {project_id}：GCP プロジェクト ID（例：customer-ai-project-123）。
• {cluster_name}：GKE クラスター名（例：tpu-cluster-prod）。
• {node_name}：ノード名またはインスタンス ID（例：tpu-node-1）。
• {workload_name}：ワークロード名／JobSet 名（例： my-training-job-456）。
• {namespace}：ワークロードの名前空間。
• {issue_time}：問題が発生した時刻（例：2026-04-14T20:00:00Z）。

時間の処理と実行ルール

1. 時間範囲の計算：問題の発生時刻 {issue_time} が指定されている場合、クエリの時間範囲を [{issue_time} - 30m] から [{issue_time} + 30m] として計算します。
   • {start_time} = {issue_time} - 30m
   • {end_time} = {issue_time} + 30m
2. 情報提供と実行の区別：ユーザーの依頼が情報提供またはクエリの作成（例：「確認するにはどうすればよいですか？」「どのように判断すればよいですか？」）である場合、または実際の GCP プロジェクトリソースを対象にできない場合は、実際のログ実行コマンドを試さずに、計算した時間範囲、ログ名、Cloud Logging のフィルターテンプレートを直接出力します。

ステップ 1：vbar_control_agent の OOM を確認する

シリアルコンソールログ（serialconsole.googleapis.com%2fserial_port_1_output）で、vbar_control_agent に関する特定の out of memory メッセージを探します。

• 使用するツール：query_logs（ライブ診断用）
• フィルターテンプレート：

シリアルコンソールログ（OOM）：

logName="projects/{project_id}/logs/serialconsole.googleapis.com%2fserial_port_1_output"
AND labels."compute.googleapis.com/resource_name"="{node_name}"
AND SEARCH(text_payload, "Memory cgroup out of memory: Killed process .* (vbar_control_ag)")
AND timestamp >= "{start_time}"
AND timestamp <= "{end_time}"

• 判定基準：vbar_control_agent に関連する Memory cgroup out of memory メッセージが存在すること。libtpu::tpunetd::VBARControlHelper::MetricsReadFromVBAR を示すスタックトレースは、有力な兆候です。
• 自動化：検出結果を報告した後、自動的に次のステップに進みます。
• 参考情報：ログパターンの例については、references/failure_signatures.md を参照してください。

ステップ 2：tpu-device-plugin のメトリクス取得失敗を調査する［低リスク］

tpu-device-plugin がメトリクスの取得失敗を報告しているか確認します。

• 使用するツール：query_logs
• フィルターテンプレート：

resource.type="k8s_container"
AND resource.labels.project_id="{project_id}"
AND resource.labels.cluster_name="{cluster_name}"
AND resource.labels.container_name="tpu-device-plugin"
AND severity=ERROR
AND textPayload:"metrics fetch failed for .* deviceID and .* device path with error: checksum didn't match with the metrics data. Corrupt data found"
AND timestamp >= "{start_time}"
AND timestamp <= "{end_time}"

• 判定基準：「metrics fetch failed」と「checksum didn't match」を示すエラーは、VBAR メモリの破損を示唆します。
• 自動化：検出結果を報告した後、自動的に次のステップに進みます。

ステップ 3：カスタムメトリクス収集の使用状況を確認する［低リスク］

クラスター構成、ワークロード、またはコンテナ仕様を調べ、カスタム TPU メトリクス収集の仕組みが導入されているか確認します。

• アクション：libtpu.sdk.tpumonitoring を使用するなどして、vBAR Control Agent の GetHostMetrics を頻繁にクエリするカスタムスクリプトやエージェントが導入されているか確認します。

• 確認コマンド：

  • Kubectl 検索（ワークロードの環境変数／仕様を調査）：

  kubectl get pods -A -o jsonpath='{range .items[*]}{.metadata.namespace}{"/"}{.metadata.name}{"\t"}{.spec.containers[*].image}{"\n"}{end}'
  

  • ログ検索フィルター（query_logs）：

  resource.type="k8s_container"
  AND resource.labels.project_id="{project_id}"
  AND resource.labels.cluster_name="{cluster_name}"
  AND textPayload:"libtpu.sdk.tpumonitoring"
  AND timestamp >= "{start_time}"
  AND timestamp <= "{end_time}"
  

• 判定基準：カスタムメトリクス収集を確認することで、競合状態の仮説を裏付けられます。

🛠️ 解決ワークフロー

解決策 1：カスタムメトリクス収集を一時的に無効にする［高リスク］

カスタムメトリクス収集エージェントが特定された場合は、無効にすることを推奨します。

• アクション：カスタムメトリクスコレクターを無効にすることを推奨します。
• 理由：デバイスのリセット中に vBAR から読み取らないようにすることで、クラッシュと OOM を防ぎます。

解決策 2：vbar_control_agent の耐障害性アップデートを待つ［低リスク］

恒久的な修正は、今後の GKE バージョンで利用可能になることを案内します。

• アクション：修正が利用可能になったら GKE をアップグレードすることを推奨します。
• 理由：アップデートされたエージェントはメモリ破損に対する耐障害性を備え、バインドされていない vBAR からの読み取りを適切に処理します。

📋 コピペ用チェックリスト

• コンテキストを取得し、[{start_time}, {end_time}] の期間を計算します。
• query_logs を使用して vbar_control_agent のセグメンテーション違反と OOM を確認します。
• query_logs を使用して tpu-device-plugin の障害を調査します。
• カスタムメトリクス収集の使用状況を調べます。
• 該当する場合は、カスタムメトリクス収集を無効にするよう案内します。
• 耐障害性アップデートを待つよう案内します。