kubeagent: el CLI de troubleshooting Kubernetes en Go

En pocas palabras: kubeagent es un CLI de troubleshooting Kubernetes de solo lectura en Go, presentado en Dev.to el 15 de julio de 2026. Detecta fallos como CrashLoopBackOff, OOMKilled o ImagePullBackOff con reglas fijas auditables. Opcionalmente se integra con Claude API para resúmenes estructurados, sin exponer datos sensibles.

Claude API es una interfaz de programación de aplicaciones desarrollada por Anthropic para acceder al modelo de lenguaje Claude, permitiendo a los desarrolladores integrar sus capacidades de generación de texto y análisis en herramientas como la CLI de solución de problemas de Kubernetes.

Julio 2026. Un dev compartió en Dev.to cómo construyó kubeagent, un CLI de troubleshooting Kubernetes en Go de solo lectura. Lo bajé, lo probé contra un clúster de pruebas, y la verdad es que funciona bien (sobre todo cuando estás a las 3 AM y no querés hacer el detective con kubectl describe).

kubeagent es una herramienta de línea de comandos en Go que escanea el estado de Kubernetes de forma pasiva y devuelve la causa raíz de pods, nodos o servicios rotos. Usa reglas deterministas, no modelos probabilísticos: mismo input, mismo output, sin internet, y podés testear cada detector como cualquier función de Go.

¿Cuáles son los modos de falla más comunes en Kubernetes?

kubeagent cubre los sospechosos de siempre que todo SRE ya se sabe de memoria, pero los junta en un solo barrido. El detector tiene reglas para:

• CrashLoopBackOff: un pod que arranca, muere y Kubernetes lo reinicia sin parar. kubeagent te dice que el contenedor falló y señala el estado del pod, sin necesidad de que vos hagas describe y adivines si es el entrypoint o falta una dependencia.
• ImagePullBackOff: la imagen no se puede bajar, ya sea porque el nombre está mal escrito o porque las credenciales del registry no andan. kubeagent lo toma directo de los eventos del pod.
• OOMKilled: el kernel mató al proceso por falta de memoria. Te muestra los límites y el estado de terminación.
• Pending / Unschedulable: ningún nodo puede asignar el pod porque los recursos no dan, hay taints o nodos cordoneados. kubeagent revisa las condiciones de los nodos y te apunta el motivo.
• Errores de Multi-Attach en volúmenes: típico en entornos con storage que no soporta múltiples montajes, deja pods trabados y nadie se explica por qué hasta que ves el evento.
• Probes fallidas: liveness o readiness que no contestan. El CLI las detecta y te marca si el probe está mal configurado o el servicio no responde.
• Leases de kubelet vencidos: un nodo que dejó de reportar, kubeagent lo identifica y te avisa que el nodo probablemente está muerto o incomunicado.
• Services con cero endpoints listos: ningún pod está sirviendo tráfico para ese Service, un clásico que te rompe la app en producción sin que suene ninguna alarma obvia.

Supongamos que desplegás un nuevo microservicio en producción, todo verde en el CI/CD, pero a los dos minutos ves que el pod está en CrashLoopBackOff. Con kubectl tenés que mirar los logs, el estado del contenedor, los eventos, y atar cabos vos solo. kubeagent te devuelve, en segundos: “Pod X en namespace Y: CrashLoopBackOff — el comando de inicio terminó con código de error 1”. De ahí saltás directo a los logs sin vueltas. Sobre eso hablamos en como en la guía de agentes sin API.

¿Cómo funciona un CLI de troubleshooting determinista?

El núcleo de kubeagent no tiene nada de magia. El autor, Iman Tabatabaei, decidió que cada modo de falla se detecte con reglas explícitas chequeando el estado real del clúster, en lugar de pedirle a un LLM que “adivine”. Él mismo lo dice en el artículo: “Hubiera sido fácil mandar todo a un LLM y dar por terminado el día. No quise eso”.

Esto significa que cuando kubeagent corre contra el mismo clúster dos veces, te da exactamente el mismo resultado. Funciona sin conexión, no necesita mandar datos a ningún lado, y podés escribir tests unitarios para cada detector, algo imposible con un modelo probabilístico. Para un equipo de infraestructura que valora la previsibilidad, es un golazo.

Las reglas se apoyan en el cliente de Go para Kubernetes (client-go) y recorren namespaces, pods, nodos y Services recopilando los estados relevantes. ¿Encontró un contenedor en estado Waiting con razón CrashLoopBackOff? Lo reporta. ¿Un nodo con condición Ready=False y sin lease reciente? Lo marca. Simple, aburrido, efectivo.

¿Cómo se integra la IA de forma opcional?

kubeagent puede llamar a la API de Claude si querés un resumen en lenguaje natural de lo que encontró, pero no le pasa información cruda del clúster. Solo envía un resumen estructurado: namespace, kind, estado, contador de reinicios y el hallazgo del detector. Nada de specs de pods, variables de entorno ni secrets. La herramienta es completamente útil sin API key; la parte de IA es un extra que podés ignorar tranquilo si preferís mantener todo offline (cosa que recomiendo, más vale pájaro en mano). Relacionado: cómo evitar el robo de secretos CI/CD.

Y ojo, al no depender de un LLM para la detección, el core sigue siendo testeable y consistente, incluso cuando Claude decide alucinar un martes a la madrugada.

¿Qué medidas de seguridad tiene un CLI read‑only?

Por defecto, kubeagent solo ejecuta operaciones GET contra la API de Kubernetes. No crea, no actualiza, no borra. Nada. Esto es fundamental: una herramienta de troubleshooting que te da miedo correr en producción no sirve. El autor lo diseñó así a propósito, con una filosofía de “primero, no romper nada”.

Existen un par de remediaciones reversibles que podés habilitar con un flag explícito (por ejemplo, hacer rollback de un Deployment trabado con una imagen mala, o des-cordonear un nodo que alguien dejó cordoneado por error). Pero sin ese flag, kubeagent es estrictamente de lectura. Si alguna vez corriste un script que hacía más de lo que decía, valorás esto.

Acordate: en un clúster productivo, el acceso de escritura debería estar reservado para pipelines y SREs con contexto. ¿Te arriesgarías a correr un binario que escribe sin leer el código? Exacto, no. kubeagent te deja ver todo sin riesgo de empeorar la situación. Complementá con siguiendo nuestra guía de diseño de claves API.

¿Cómo se construye un CLI en Go para Kubernetes?

El proyecto usa client-go, la biblioteca oficial de Go para interactuar con la API de Kubernetes, y organiza el código en una capa de detección con funciones puras que evalúan condiciones. Sobre eso, un módulo opcional toma los resultados estructurados y los formatea para la API de Claude si el usuario lo pide. Todo se compila en un solo binario estático, sin dependencias externas en runtime, listo para copiar a cualquier máquina con acceso al clúster.

Si alguna vez te planteaste escribir tu propia CLI de troubleshooting, el artículo original de Tabatabaei (publicado el 15 de julio de 2026 en Dev.to) es un excelente punto de partida. Ahí explica cómo modela los distintos recursos de Kubernetes y cómo evita falsos positivos con chequeos adicionales.

¿Cuál es la diferencia entre un enfoque determinista y uno basado en IA?

No es que uno sea mejor que el otro en todo; depende del contexto. kubeagent combina ambos, pero tiene bien separadas las responsabilidades:

Enfoque determinista	Enfoque basado en IA
Siempre el mismo resultado para el mismo estado del clúster	Puede variar entre llamadas, sobre todo si el modelo recibe prompts distintos o se actualiza
Funciona completamente offline, sin latencia de red	Requiere conexión y tiene costo por request
100 % testeable con unit tests	Testear el comportamiento exacto es casi imposible; solo podés evaluar salidas aproximadas
No manda datos sensibles fuera del clúster	Necesita enviar información (por más resumida que sea); hay que ser cuidadoso para no exponer secrets
Ideal para detección rápida, automatizable en pipelines	Ideal para resumir hallazgos en lenguaje humano, armar reportes o sugerir próximos pasos

La jugada de kubeagent es usar el determinismo para el diagnóstico pesado y dejar que Claude haga el speech‑to‑text de la posta, solo si vos querés. Eso evita que un modelo alucine la causa de un incidente mientras vos estás en una call de war room. Tema relacionado: aprende a convertir tu CLI en una API.

¿Dónde descargar kubeagent y cómo empezar?

El proyecto está documentado en el artículo original de Dev.to, donde el autor publica el código y las instrucciones para compilarlo o bajar el binario. Una vez que lo tenés, ejecutar algo como kubeagent analyze --kubeconfig ~/.kube/config dispara el escaneo completo de tu clúster actual y te larga los hallazgos por consola.

Si querés probarlo sin miedo, podés levantarte un k3s en un VPS chico. En donweb.com tenés opciones de cloud y VPS que arrancan barato para montar un clúster de pruebas. Después clonás el repo, compilás con Go, y en cinco minutos estás viendo si tu laboratorio tiene algún pod fallando.

Errores comunes al hacer troubleshooting en Kubernetes

A lo largo de los años vi a mucha gente cometer los mismos tropiezos. Acá van tres que kubeagent ayuda a esquivar:

• Tratar a kubectl describe como un oráculo. El describe te tira una pared de texto con eventos y condiciones, pero no te dice “el problema es X”. Muchos se quedan mirando ese muro y pierden tiempo. kubeagent aplica reglas de interpretación; vos podés hacer lo mismo, pero requiere experiencia y suerte.
• No filtrar los permisos del CLI. He visto gente corriendo herramientas caseras con un service account de cluster‑admin, cuando solo necesitaban leer eventos. kubeagent nació con permisos de lectura por defecto; si vos construís tu propia CLI, poné RBAC mínimo o vas a llorar sangre el día que un script borre algo por error.
• Confundir correlación con causalidad. Un pod en CrashLoopBackOff y un nodo con mucha memoria usada no siempre están relacionados. Un CLI determinista te da el estado puntual, pero no te hace las inferencias de contexto; eso lo tenés que hacer vos. kubeagent te lista los hallazgos, no te escribe el RCA final.

Preguntas Frecuentes

¿Qué es kubeagent?

kubeagent es un CLI de troubleshooting Kubernetes de solo lectura, escrito en Go, que detecta fallos como CrashLoopBackOff, OOMKilled y Services sin endpoints aplicando reglas deterministas sobre el estado del clúster. Fue creado por Iman Tabatabaei y presentado el 15 de julio de 2026.

¿Necesito una API key de Claude para usar kubeagent?

No. La integración con Claude es opcional y solo sirve para generar un resumen en lenguaje natural de los hallazgos. La herramienta funciona perfectamente offline sin ninguna API key.

¿Kubeagent modifica mi clúster de Kubernetes?

Por defecto, no. kubeagent solo realiza llamadas GET a la API de Kubernetes. Existen algunas remediaciones reversibles (como un rollback) que requieren un flag explícito, pero sin ese flag, la herramienta es estrictamente de lectura.

¿Qué fallos detecta kubeagent?

Detecta CrashLoopBackOff, ImagePullBackOff, OOMKilled, pods Pending/Unschedulable, errores de Multi‑Attach en volúmenes, fallos en probes de liveness/readiness, leases de kubelet vencidos y Services con cero endpoints listos, entre otros.

¿Funciona sin conexión a internet?

Sí. El núcleo determinista no necesita acceso a internet; solo requiere conectividad con el clúster de Kubernetes. La parte de resumen con Claude sí necesita conexión, pero es opcional.

Conclusión

kubeagent no reemplaza a un SRE con años de experiencia, pero le ahorra los primeros diez minutos de detective en cada incidente. La decisión de hacerlo determinista y read‑only muestra que el autor conoce el dolor real del debugging en producción. Para equipos en Latinoamérica, donde a veces laburamos con conectividad intermitente o restricciones de compliance que impiden mandar datos a un SaaS externo, tener una herramienta que corre offline y no expone información sensible es un diferencial fuerte.

Si manejás Kubernetes en producción, bajate el binario, probalo en staging y fijate cuánto tiempo te ahorra la próxima vez que salte una alerta a la madrugada.

Fuentes

• Artículo original en Dev.to — Publicación del autor del 15 de julio de 2026 con el detalle completo de la arquitectura y el código.
• client‑go library — Documentación oficial de la biblioteca de Go para interactuar con la API de Kubernetes.
• Kubernetes Debugging — Guía oficial de Kubernetes sobre diagnóstico de clústeres y aplicaciones.