Depura tus microservicios de Kubernetes en tu propia máquina
kubedebugger intercepta el tráfico real de un servicio del clúster, escala su deployment a cero y lo redirige a tu 127.0.0.1. Tu código, tu IDE, tus breakpoints, los datos del entorno. Al desconectar, el clúster se restaura solo.
# conectas, listas e interceptas: tres comandos $ kdb connect ✓ contexto aks-prod-eu · namespace tienda $ kdb list store-front ClusterIP interceptable orders ClusterIP interceptable $ kdb intercept orders --port 8080 --env-file .env ✓ deployment escalado a 0 · fake-proxy desplegado · túnel activo ✓ tráfico del clúster → 127.0.0.1:8080 (Ctrl+C para restaurar) # en otra terminal: F5 en tu IDE con breakpoints. # Las peticiones REALES del entorno llegan a tu proceso local.
Depurar en Kubernetes no debería ser un ritual
Si desarrollas contra un clúster, conoces la coreografía: reconstruir la imagen con herramientas de depuración, esperar el pipeline, mirar logs a ciegas, repetir. Y para ver un breakpoint, o montas un entorno paralelo medio roto o contaminas el clúster con tooling que no quieres en producción.
kubedebugger rompe eso: el servicio sigue desplegado donde debe, pero su tráfico —el real, con sus cabeceras, sus tokens y sus productores de eventos— viaja a tu proceso local mientras depuras. Ni entornos espejo, ni imágenes especiales, ni cambios en tus manifiestos.
Cómo funciona, sin humo
Tres piezas en total. Dos viven en el clúster y una en tu máquina.
| Componente | Dónde vive | Qué hace |
|---|---|---|
CLI kdb |
Tu máquina | Conectar, listar, interceptar, restaurar. Toda la lógica está aquí; el resto son ejecutores. Incluye interfaz interactiva (kdb tui). |
| Manager | Clúster (namespace central o el del equipo) | API de sesiones, relay del túnel y watchdog de recuperación. Ejecuta todas las mutaciones con su propia ServiceAccount. |
| Fake-proxy | Clúster (pod ligero por sesión) | Sustituye al workload: recibe el tráfico del Service y lo tunela a tu máquina, o sirve respuestas simuladas si usas mocks. |
| Extensión VS Code (opcional) | Tu editor | Una sola vista: conexión, intercepts activos, servicios interceptables y sesiones ajenas. Ejecuta kdb por debajo; todo lo que hace la UI se puede hacer en terminal. |
Anatomía de un intercept
- Snapshot.
kdbguarda el estado original del deployment (réplicas, selector, imagen). - Escala a cero. El workload original deja de correr: no hay doble procesamiento de mensajes ni escrituras duplicadas.
- Fake-proxy. Se despliega un pod mínimo y el Service se redirige a él. Para el resto del clúster, el servicio «sigue ahí».
- Túnel. El fake-proxy envía el tráfico hacia tu máquina por un port-forward autenticado con token a través del API server. Nada se expone: ni LoadBalancer, ni Ingress, ni NodePort.
- Depuras. Las peticiones llegan a tu
127.0.0.1:puerto. Con--env-file, tu proceso local arranca con las variables del pod (connection strings incluidas): tu local consume y publica en los brokers y bases de datos reales del entorno. - Restauración. Con
detach(o Ctrl+C) todo vuelve a su estado exacto. Si tu portátil muere sin desconectar, el watchdog del manager restaura el clúster tras un periodo de gracia (--daemon-grace, 2 min por defecto).
pods get/list y
pods/portforward create; todas las escrituras las hace el manager con su
ServiceAccount, auditable como cualquier cuenta de servicio del clúster.
Elige cuánto tráfico quieres ver
Y comparte el mismo servicio con el resto del equipo sin pisarse.
forward
Todo el tráfico del servicio llega a tu máquina. Ideal para reproducir un bug concreto con carga real o seguir una petición end-to-end con breakpoints.
kdb intercept orders \ --port 8080
mock
El fake-proxy responde con respuestas que tú defines en YAML: estados, cuerpos, latencias, porcentaje de errores. Sin levantar siquiera el servicio en local.
kdb intercept orders \ --mode mock \ --mocks mocks.yaml
híbrido
Filtra por cabecera o ruta: lo que te interesa va a tu máquina, el resto lo atienden los mocks. Varios desarrolladores pueden interceptar el mismo servicio con filtros distintos.
kdb intercept orders \ --mode hybrid \ --http-header x-debug=tu-usuario \ --mocks mocks.yaml
# mocks.yaml — el fake responde por ti routes: - path: /api/orders method: GET status: 200 body: {"orders": [], "degraded": true} latencyMs: 120 - path: /api/orders method: POST status: 503 # prueba cómo reacciona tu cliente a un error errorRate: 0.3
Instalación en dos roles
El administrador instala una vez por clúster; los desarrolladores no instalan nada en el clúster, solo el binario en su máquina.
Manager central en kubedebugger-system + acceso para el grupo de Entra ID:
$ kdb install ✓ namespace kubedebugger-system · deployment manager · secret de sesión · RBAC $ kdb grant-devs --group <objectId-del-grupo-Entra> ✓ el grupo de devs ya puede usar kdb en todos los namespaces
Entra un desarrollador nuevo al grupo y ya puede trabajar, sin ejecutar nada ni
dar altas por persona. ¿Prefieres aislamiento por equipo? kdb install
--namespace <ns> despliega un manager namespaced con RBAC limitado a ese
namespace. ¿Un namespace delicado? kubectl label ns <ns>
kubedebugger.es/allow-intercept=false y queda blindado.
Descarga el paquete, instala y conecta. Sin permisos de administrador, sin tocar el clúster por tu cuenta:
# Windows: descomprime y ejecuta install.ps1 (copia kdb al PATH e instala la extensión) # Linux/macOS: descomprime el tar.gz y mueve ./kdb a tu PATH $ kdb connect ✓ contexto y namespace fijados (se recuerdan entre sesiones) $ kdb use-namespace tienda $ kdb intercept store-front --port 8080 --env-file .env ✓ tráfico real → 127.0.0.1:8080
En clústeres corporativos con permisos restringidos, kdb detecta el 403
y opera automáticamente a través del manager. Si tu equipo no usa la terminal,
la extensión de VS Code y kdb tui cubren el mismo flujo con interfaz gráfica.
Diseñado por y para gente que opera clústeres
Breakpoints, no prints
Depura con tu IDE de siempre: breakpoints, inspección de variables, paso a paso. Contra el tráfico real del entorno.
Cero cambios en tus imágenes
Ni sidecars ni agentes de depuración en tus Dockerfiles. Tus manifiestos y tu pipeline quedan intactos.
Entornos reales, sin duplicar
Tu proceso local consume los brokers y bases de datos del entorno con las variables del pod. Sin réplicas fantasma duplicando eventos.
Pensado para clústeres corporativos
Modo restringido para perfiles mínimos (solo pods + port-forward), alta vía grupo de Entra ID y fallback automático al manager ante un 403.
Autocuración
Snapshot del estado original, restauración exacta al desconectar y watchdog que levanta el clúster si tu máquina desaparece sin despedirse.
Colaboración visible
Sesiones de todo el equipo con propietario y expiración; intercepts simultáneos con filtros por cabecera; recuperación de sesiones huérfanas.
Nada expuesto
Todo el tráfico viaja por port-forward del API server: funciona en clústeres privados sin abrir ni un puerto ni crear un Ingress.
Gratuito de verdad
Todas las funciones, sin planes, sin cuentas, sin telemetría. Licencia MIT: úsalo en personal y en corporativo.
El modelo de permisos, sobre la mesa
Sin sorpresas: aquí está exactamente lo que se necesita según el rol.
| Rol | Permisos necesarios |
|---|---|
| Admin que instala (una vez) | Crear namespaces, RBAC, deployments y secrets — lo estándar para desplegar cualquier componente en el clúster. |
Desarrollador (modo central + grant-devs) | pods get/list + pods/portforward create en kubedebugger-system. Nada más, y heredado por grupo, no por persona. |
| Desarrollador (modo por namespace) | El mismo par de permisos, pero en su namespace: es el perfil habitual de un dev en un AKS corporativo. |
Autenticación del túnel
Cada sesión viaja con un token aleatorio guardado en un Secret del clúster, verificado en tiempo constante por el manager. El tramo tu-máquina → clúster va cifrado por el propio API server (port-forward TLS).
Contención
Namespaces de no-desarrollo protegidos con kubedebugger.es/allow-intercept=false, periodo de gracia configurable del watchdog y kdb recover para restaurar cualquier sesión ajena a mano.
kubedebugger v0.1.0
Un binario para tu máquina, imágenes para tu clúster y, si quieres, la extensión de VS Code.
Windows
kubedebugger-windows-amd64.zipkdb.exe + extensión VSIX + install.ps1 / uninstall.ps1
Descargar zipmacOS (Apple Silicon)
kubedebugger-unix.tar.gzIncluye kdb (darwin-arm64) y la extensión VSIX
Descargar tar.gzInstalador Windows
kubedebugger-setup.msiAsistente clásico siguiente-siguiente: Program Files, PATH y extensión. Requiere admin
Descargar MSIExtensión VS Code
kubedebugger-extension.vsixIncluida también en los paquetes anteriores
Descargar VSIXDescargas servidas desde GitHub Releases, generadas automáticamente por GitHub Actions desde el código fuente etiquetado. Verifica la integridad con SHA256SUMS.txt.
kubectl configurado contra tu clúster y el binario
kdb. Para la extensión de VS Code, VS Code ≥ 1.90. Los desarrolladores no
necesitan Go ni Node: eso es solo para compilar desde fuente.
KUBEDEBUGGER_MANAGER_IMAGE y
KUBEDEBUGGER_FAKE_IMAGE apuntas a tu registro y no repites flags.
Estado y hoja de ruta
Preferimos decir lo que falta antes que vender humo. Esto es lo validado y lo que viene.
Validado (v0.1.0)
Validación end-to-end contra clúster real de pruebas: intercept forward y mock, restauración exacta del deployment, watchdog de sesiones huérfanas, modo restringido con fallback al manager y suite de tests de CLI, manager, fake-proxy y extensión.
En camino (v1)
TLS extremo a extremo en el tramo interno del túnel, filtrado por cabecera integrado en el camino del tráfico, alta disponibilidad del manager, métricas y publicación de imágenes en registro público para instalar sin tocar un Dockerfile.
Preguntas que haría un sysadmin
¿De verdad es 100% gratuito?
Sí. Todas las funciones, sin planes de pago, sin registro de usuarios y sin telemetría de ningún tipo. Se distribuye bajo licencia MIT: puedes usarlo en proyectos personales y en entornos corporativos, modificarlo y redistribuirlo.
¿Es código abierto?
El proyecto se distribuye bajo licencia MIT. La publicación del árbol de fuentes completo está en evaluación; los paquetes que descargas incluyen el texto de la licencia y son de libre uso, estudio y redistribución conforme a ella. Si la apertura de fuentes es un requisito para tu organización, escríbenos por contacto: nos ayuda a priorizar.
¿Qué puede romper un desarrollador en el clúster?
Muy poco, y todo se recupera. El intercept guarda un snapshot del deployment y lo restaura al desconectar; si la máquina del dev desaparece, el watchdog del manager lo restaura tras el periodo de gracia; cualquier sesión ajena se puede restaurar con kdb recover; y los namespaces que quieras blindar se marcan con kubedebugger.es/allow-intercept=false. Además, el dev nunca ejecuta mutaciones: las hace el manager con su ServiceAccount.
¿Funciona con un AKS privado?
Sí. El CLI y el túnel usan el port-forward del API server: no hace falta exponer ningún servicio, LoadBalancer ni Ingress, y no depende de que el clúster tenga endpoint público.
¿Qué lenguajes y frameworks soporta?
Todos los que escuchen en un puerto TCP local: Go, Java, Node, .NET, Python, Rust… kubedebugger no instrumenta tu proceso, solo le entrega el tráfico en 127.0.0.1. Si tu IDE puede depurar un servidor local, puede depurar un servicio interceptado.
¿Y si dos personas interceptan el mismo servicio?
Con el modo híbrido, cada una se filtra su tráfico por cabecera (--http-header) o ruta, y el resto lo atienden los mocks. Todas las sesiones son visibles con kdb status --all, con propietario y expiración.
¿Qué datos salen de mi máquina o del clúster?
Ninguno hacia nosotros. El tráfico interceptado viaja del clúster a tu máquina por el túnel; no hay servidor intermedio de kubedebugger, no hay cuentas, y la herramienta no envía métricas ni telemetría. Las herramientas de terceros que ya usas (kubectl, tu clúster, tu registro de imágenes) siguen siendo cosa tuya.
¿Sirve para clústeres locales (kind, minikube, Docker Desktop)?
Sí, y de hecho el propio proyecto se valida así de forma automatizada. El flujo es idéntico al de un AKS corporativo: kdb install, kdb connect, kdb intercept.
¿Cómo se actualiza?
Descarga el paquete nuevo y ejecuta de nuevo install.ps1 / sustituye el binario. kdb install es idempotente (upsert) y conserva el secret de sesión entre reinstalaciones; kdb version te dice qué versiones corren el CLI y el manager.