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

TPU 连接失败和 VBAR OOM 故障排查

使用此技能，系统地诊断和预防 TPU v6e 节点上的 vbar_control_agent 段错误和内存不足（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>"

• 判断逻辑：包含“metrics fetch failed”和“checksum didn't match”的错误表明 vBAR 内存可能已损坏。
• 自动化：报告发现后自动进入下一步。

步骤 3：检查是否使用了自定义指标收集机制 [低风险]

询问用户是否部署了自定义 TPU 指标收集机制。

• 操作：询问用户是否使用自定义脚本或 Agent（例如， 使用 libtpu.sdk.tpumonitoring），频繁从 vBAR Control Agent 查询 GetHostMetrics。
• 判断逻辑：确认使用了自定义指标收集机制，有助于验证竞态条件假设。
• 自动化：停止并等待用户回复后再继续处理。

🛠️ 解决工作流

解决方案 1：暂时禁用自定义指标收集 [高风险]

如果确认存在自定义指标收集 Agent，建议用户暂时将其禁用。

• 操作：建议禁用自定义指标收集器。
• 理由：防止设备重置期间读取 vBAR，从而避免崩溃和 OOM。
• 自动化：在提出此建议或采取行动前，停止并在 bug 讨论帖中请求用户明确批准。

解决方案 2：等待 vbar_control_agent 弹性改进 [低风险]

告知用户，永久修复将在未来的 GKE 版本中提供。

• 操作：修复可用后，建议升级 GKE。
• 理由：更新后的 Agent 能够抵御内存损坏，并妥善处理对未绑定 vBAR 的读取。
• 自动化：继续报告此发现。

📋 复制粘贴检查清单

• 获取上下文并计算 [T - 30m, T + 30m] 时间窗口。
• 使用 query_logs 检查 vbar_control_agent 是否发生段错误和 OOM。
• 使用 query_logs 调查 tpu-device-plugin 故障。
• 询问用户是否在使用自定义指标采集。
• 如适用，建议禁用自定义指标采集（高风险）。
• 建议等待弹性更新。