/gke-ai-troubleshooting-tpu-vbar-oom

name: gke-ai-troubleshooting-tpu-vbar-oom
description: >-
  Diagnoses and prevents vbar_control_agent segfaults, out-of-memory (OOM) errors,
  and TPU device initialization failures on TPU v6e nodes in GKE caused by race
  conditions during TPU device resets or high-frequency metrics polling. Use when
  troubleshooting vbar_control_agent crashes, memory cgroup OOMs in serial console
  logs, tpu-device-plugin metrics checksum corruption errors, or custom TPU metrics
  collection conflicts on GKE TPU v6e nodes. Don't use for general non-TPU container
  OOM troubleshooting or standard GKE node lifecycle operations.
metadata:
  category: CloudObservabilityAndMonitoring

TPU Connection Failure and VBAR OOM Troubleshooting

Use this skill to systematically diagnose and prevent `vbar_control_agent` segfaults and Out-Of-Memory (OOM) errors on TPU v6e nodes.

⚠️ Prerequisites

• Cloud Logging must be enabled for the project.
• Access to the project and cluster via `gcloud` or equivalent tool.

🔍 Diagnostic Workflow

Step 0: Context Acquisition & Time Window Definition

Independently gather required context using available GCP/GKE tools or use the provided `{variable}` placeholders:

• `{project_id}`: The GCP Project ID (e.g., `customer-ai-project-123`).
• `{cluster_name}`: The GKE Cluster Name (e.g., `tpu-cluster-prod`).
• `{node_name}`: The Node Name or Instance ID (e.g., `tpu-node-1`).
• `{workload_name}`: The Workload Name / JobSet Name (e.g.,

`my-training-job-456`).

• `{namespace}`: The Workload Namespace.
• `{issue_time}`: The timestamp of the issue (e.g., `2026-04-14T20:00:00Z`).

Time Handling & Execution Rules

1. **Window Calculation**: If an issue timestamp `{issue_time}` is provided, calculate the query time window as `[{issue_time} - 30m]` to `[{issue_time} + 30m]`.

• Let `{start_time}` = `{issue_time} - 30m`
• Let `{end_time}` = `{issue_time} + 30m`

2. **Informational vs. Live Execution**: If the user request is informational or query-formulation (e.g. "How can I check...", "How do I determine..."), or if live GCP project resources are not actively targetable, directly output the calculated time window, log names, and Cloud Logging filter templates without attempting live log execution commands.

Step 1: Check for `vbar_control_agent` OOMs

Look for specific `out of memory` messages from `vbar_control_agent` in serial console logs (`serialconsole.googleapis.com%2fserial_port_1_output`).

• **Tool to use**: `query_logs` (for live diagnostics)
• **Filter Templates**:

**Serial Console Logs (OOMs):**

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}"

• **Logic**: Presence of `Memory cgroup out of memory` messages related to

`vbar_control_agent`. Stack traces pointing to `libtpu::tpunetd::VBARControlHelper::MetricsReadFromVBAR` are a strong indicator.

• **Automation**: Proceed to next step automatically after reporting findings.
• **Reference**: See `references/failure_signatures.md` for example log

patterns.

Step 2: Investigate `tpu-device-plugin` Metrics Fetch Failures [Low Risk]

Check if `tpu-device-plugin` is reporting metric fetch failures.

• **Tool to use**: `query_logs`
• **Filter Template**:

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}"

• **Logic**: Errors indicating "metrics fetch failed" with "checksum didn't

match" suggest vBAR memory corruption.

• **Automation**: Proceed to next step automatically after reporting findings.

Step 3: Check for Custom Metrics Collection Usage [Low Risk]

Inspect cluster configurations, workloads, or container specs to determine if custom TPU metrics collection mechanisms are deployed.

• **Action**: Check if custom scripts or agents (e.g., using

`libtpu.sdk.tpumonitoring`) are deployed that frequently query `GetHostMetrics` from `vBAR Control Agent`.

• **Verification Commands**:

• **Kubectl Search (Inspect workload env/specs)**:

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

• **Log Search Filter (`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}"

• **Logic**: Confirmation of custom metrics collection helps confirm the race

condition hypothesis.

🛠️ Resolution Workflow

Resolution 1: Temporarily Disable Custom Metrics Collection [High Risk]

If a custom metrics collection agent is identified, recommend disabling it.

• **Action**: Recommend disabling the custom metrics collector.
• **Justification**: Prevents reads from vBAR during device resets, stopping

crashes and OOMs.

Resolution 2: Await `vbar_control_agent` Resiliency Update [Low Risk]

Advise that a permanent fix will be available in a future GKE version.

• **Action**: Recommend upgrading GKE when the fix is available.
• **Justification**: The updated agent will be resilient to memory corruption

and gracefully handle reads from unbound vBARs.

📋 copypaste checklist

• [ ] Acquire context and compute