Skills Agentes

Gke Ai Troubleshooting Tpu Vbar Oom

Diagnostica y previene segfaults de vbar_control_agent, errores OOM y fallos de inicialización de dispositivos TPU en nodos TPU v6e de GKE por condiciones de carrera.

Oficial
Estrellas
20.2k

en todo el repo

Actividad
56

0–100, la ruta de este skill

Actualizado
hace 3 meses

último commit aquí

Commits
1

últimos 90 días

Contexto
1.6k tok

137 tok en reposo

Paquete
3 archivos

9 KB

Instalar

Funciona con cualquier agente que lea SKILL.md

npx -y skills add google/skills --skill gke-ai-troubleshooting-tpu-vbar-oom --agent claude-code

Se instala solo en este repositorio.

Este skill reads environment config.

Qué hace

  • Calcula ventana temporal de ±30 min alrededor de {issue_time} para buscar en logs
  • Busca en serial console logs OOMs de vbar_control_agent con filtros SQL predefinidos
  • Revisa logs de tpu-device-plugin para errores de checksum en métricas
  • Inspecciona workloads y logs para detectar recolectores de métricas TPU personalizados
  • Recomienda deshabilitar métricas custom o esperar una actualización de resiliencia de GKE

Úsalo cuando

  • Al depurar crashes de vbar_control_agent
  • Al encontrar OOMs de memory cgroup en logs de la serial console
  • Al ver errores de checksum corruption en métricas de tpu-device-plugin
  • Al sospechar conflictos por recolección de métricas TPU personalizada en nodos TPU v6e de GKE

No lo uses cuando

  • Para troubleshooting general de OOM en contenedores no TPU
  • Para operaciones estándar del ciclo de vida de nodos de GKE

Qué lo activa

Di cualquiera de estas frases y el agente debería cargar este skill.

  • “¿Por qué está fallando vbar_control_agent con OOM en mi nodo TPU v6e?”
  • “Revisa los logs de la serial console del nodo tpu-node-1 por errores de memoria”
  • “El tpu-device-plugin reporta checksum corrupt data, ¿qué está pasando?”

SKILL.md

En inglés

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 [{start_time}, {end_time}] window.
  • Check for vbar_control_agent segfaults and OOMs using query_logs.
  • Investigate tpu-device-plugin failures using query_logs.
  • Inspect for custom metrics collection usage.
  • Advise disabling custom metrics collection if applicable.
  • Advise awaiting resiliency update.

Reproducido de google/skills bajo licencia Apache-2.0. Leer esta página en markdown.

Archivos

3 archivos en el paquete. Solo se lee SKILL.md al activarse — las referencias se cargan si el skill decide que las necesita.

Antes de instalar

Requiere que Cloud Logging esté habilitado en el proyecto y acceso al proyecto/clúster vía gcloud o herramienta equivalente.

Necesita en el PATH:gcloud

Variables de entorno:FILTER_1FILTER_2PROJECT_ID

Detalles

Creador
google
Licencia
Apache-2.0
Recursos incluidos
scripts en bash + referencias
Repositorio
google/skills
Código fuente
Ver SKILL.md

Etiquetas

Más de google/skills

Este repo incluye 131 skills. Si instalas uno, normalmente ya tienes los demás. Ver el pack skills entero y su comando de instalación

Configura políticas de alerta de buenas prácticas para agentes de IA usando métricas OpenTelemetry (OTel), generando la salida como archivos de configuración Terraform (.tf).

Costo de contexto al activarse
4.2k tok
Tamaño del paquete
28 archivos
Última actualización
hace 2 meses
Oficialdevops infraestructura

Descubre requisitos de forma interactiva y diseña arquitecturas de solución multiproducto, planos de solución y recomendaciones de despliegue para cargas de trabajo complejas en Google Cloud.

Costo de contexto al activarse
3.4k tok
Tamaño del paquete
5 archivos
Última actualización
hace 2 meses
Oficialdevops infraestructura

Gestiona la provisión de clústeres GKE, credenciales, elección entre Autopilot y Standard, y despliegue de workloads en Google Kubernetes Engine.

Costo de contexto al activarse
914 tok
Tamaño del paquete
6 archivos
Última actualización
hace 3 meses
Oficialdevops infraestructura

Gestiona y orquesta prompts en Agent Platform: crear, listar, recuperar, versionar o eliminar prompts gestionados; no sirve para entrenamiento ni despliegue de modelos.

Costo de contexto al activarse
2.2k tok
Tamaño del paquete
2 archivos
Última actualización
hace 2 meses
Oficialaprendizaje

Ajuste fino de modelos en Agent Platform: para afinar modelos abiertos o Gemini. No usar para entrenar fuera de Agent Platform, desplegar a endpoints o gestionar endpoints de serving.

Costo de contexto al activarse
6.4k tok
Tamaño del paquete
12 archivos
Última actualización
hace 2 meses
Oficialaprendizaje

Planifica, ejecuta y valida actualizaciones y mantenimiento de clusters de Google Kubernetes Engine (GKE), tanto Standard como Autopilot, con planes, checklists y runbooks con comandos gcloud.

Costo de contexto al activarse
5k tok
Tamaño del paquete
4 archivos
Última actualización
hace 2 meses
Oficialdevops infraestructura

Skills relacionados

Configura políticas de alerta de buenas prácticas para agentes de IA usando métricas OpenTelemetry (OTel), generando la salida como archivos de configuración Terraform (.tf).

Costo de contexto al activarse
4.2k tok
Tamaño del paquete
28 archivos
Última actualización
hace 2 meses
Oficialdevops infraestructura

Despliega modelos abiertos o pesos personalizados de Model Garden a endpoints de Agent Platform, revisa el estado de un despliegue en curso, o limpia recursos retirando modelos y borrando endpoints.

Costo de contexto al activarse
5.1k tok
Tamaño del paquete
5 archivos
Última actualización
hace 2 meses
Oficialdevops infraestructura

Gestiona serving endpoints de Agent Platform: crear, listar, describir, actualizar o eliminar endpoints, y resolver errores de permisos, cuota o recursos ocupados. No sirve para desplegar modelos ni ejecutar evaluaciones.

Costo de contexto al activarse
1.5k tok
Tamaño del paquete
1 archivo
Última actualización
hace 3 meses
Oficialdevops infraestructura