gke-ai-troubleshooting-tpu-connection-failure-vbar-oom

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

このスキルを使用して、TPU v6e ノードで発生する vbar_control_agent のセグメンテーション違反と Out-Of-Memory（OOM）エラーを体系的に診断し、予防します。

⚠️ 前提条件

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

🔍 診断ワークフロー

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

トラブルシューティングを開始するには、ユーザーから次の情報を取得します。

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

時刻の取り扱いルール

1. 相対時刻は受け付けない：「X 分前」や「たった今」とユーザーが答えた場合は、作業を中断して正確なタイムスタンプまたは具体的な時間枠を尋ねます。
2. 時間枠の計算：ユーザーが開始時刻または「およそ」の時刻 T を提示した場合、クエリの時間枠を [T - 30m] から [T + 30m] として計算します。
   • Start_Time = T - 30m とします
   • End_Time = T + 30m とします

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

シリアルコンソールログから、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>"

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

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

ユーザーに、独自に導入した TPU メトリクス収集の仕組みがあるか確認します。

• 対応：vBAR Control Agent から GetHostMetrics を頻繁にクエリするカスタムスクリプトやエージェント（libtpu.sdk.tpumonitoring を使用するものなど）を使っているか、ユーザーに尋ねます。
• 判定方法：カスタムメトリクス収集の利用が確認できれば、競合状態の仮説を裏付けるのに役立ちます。
• 自動化：解決策に進む前に処理を中断し、ユーザーの回答を待ちます。

🛠️ 解決ワークフロー

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

カスタムメトリクス収集エージェントが特定された場合は、ユーザーに一時的に無効にするよう案内します。

• 対応：カスタムメトリクス収集ツールを無効にするよう推奨します。
• 理由：デバイスのリセット中に vBAR からの読み取りを防ぎ、クラッシュと OOM を抑止します。
• 自動化：この推奨を行う前、または対応を実施する前に処理を中断し、バグスレッドでユーザーから明示的な承認を求めます。

解決策 2：vbar_control_agent のレジリエンス向上を待つ［低リスク］

恒久的な修正は今後の GKE バージョンで提供されることをユーザーに案内します。

• 対応：修正が利用可能になったら、GKE をアップグレードするよう推奨します。
• 理由：更新されたエージェントはメモリ破損に対するレジリエンスを備え、バインドされていない vBAR からの読み取りを適切に処理します。
• 自動化：この結果を報告します。

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

• コンテキストを取得し、[T - 30m, T + 30m] の期間を算出します。
• query_logs を使用して、vbar_control_agent のセグメンテーション違反と OOM を確認します。
• query_logs を使用して、tpu-device-plugin の障害を調査します。
• カスタムメトリクス収集の使用状況についてユーザーに確認します。
• 該当する場合は、カスタムメトリクス収集を無効にするよう助言します（高リスク）。
• レジリエンスの更新を待つよう助言します。