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 指标收集机制。

• 操作：检查是否部署了会频繁从 vBAR Control Agent 查询 GetHostMetrics 的自定义脚本或 Agent（例如使用 libtpu.sdk.tpumonitoring 的脚本或 Agent）。

• 验证命令：

  • 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：暂时禁用自定义指标收集［高风险］

如果发现了自定义指标收集 Agent，建议将其禁用。

• 操作：建议禁用自定义指标收集器。
• 理由：防止设备重置期间从 vBAR 读取数据，从而阻止崩溃和 OOM。

解决方案 2：等待 vbar_control_agent 韧性更新［低风险］

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

• 操作：修复可用后，建议升级 GKE。
• 理由：更新后的 Agent 将能够抵御内存损坏，并妥善处理从未绑定 vBAR 的读取操作。

📋 复制粘贴检查清单

• 获取上下文并计算 [{start_time}, {end_time}] 时间窗口。
• 使用 query_logs 检查 vbar_control_agent 段错误和 OOM。
• 使用 query_logs 调查 tpu-device-plugin 故障。
• 检查是否使用了自定义指标收集。
• 如适用，建议禁用自定义指标收集。
• 建议等待韧性更新。