Conceptos
Arquitectura
Backend en Go con cachés de informers, VictoriaMetrics para el histórico (incluido en el chart de Helm y en Compose) y un agente solo saliente. Frontend en React con actualizaciones en vivo por WebSocket.
En esta página
Diagrama del sistema
(Go) (React 18 · TS · Vite 5 · Tailwind) Workspace de Go
Monorepo con go.work que contiene cuatro módulos:
apps/api: servidor backend principal (entrada:cmd/server/main.go)packages/agent: el agente del clúster (con su propia línea de versiones,1.x)packages/proto: tipos gRPC/protobuf generados que comparten la API y el agentepackages/shared: utilidades de Go compartidas
Las dos mitades
Backend (por instalación): lee la API de Kubernetes con informers
compartidos, evalúa los insights, sirve la API REST/WebSocket y guarda el
estado (usuarios, ajustes, episodios de insights, hallazgos de seguridad, el
registro de auditoría, las conversaciones de Kobi) en un BoltDB embebido. Las
métricas históricas van a VictoriaMetrics: el chart de Helm y el stack de
Compose ejecutan una instancia de un solo nodo junto a la API; el binario
único y la imagen de un solo contenedor no incluyen ninguna, y leen cualquier
endpoint compatible con VictoriaMetrics al que apuntes
KUBEBOLT_METRICS_STORAGE_URL.
Agente (por clúster, opcional): se conecta hacia fuera por gRPC
(AgentChannel) y envía muestras de métricas, que salen de sus recolectores
integrados de kubelet y nodo, de un sidecar de scraping vmagent incluido o de
leer tu Prometheus existente (promRead). También transporta los flujos de red
de Hubble para la pestaña Reliability y la disposición Traffic del
Cluster Map, las series de OpenCost para la pestaña
Cost y, en modo reader u operator, hace de proxy de las
llamadas a la API de Kubernetes de los clústeres a los que el backend no llega
directamente, incluidas las sesiones de exec, port-forward y explorador de
archivos en modo operator. Consulta
Conectar clústeres.
Paquetes clave del backend
Todos bajo apps/api/internal/.
| Paquete | Propósito |
|---|---|
cluster/manager.go | Registro y ciclo de vida de los clústeres: contextos de kubeconfig, clústeres por proxy del agente y solo de métricas, nombres visibles, cambio de contexto; ejecuta el bucle de evaluación de insights (cada 60s) |
cluster/connector.go | Informers compartidos + cliente dinámico; la sincronización de la caché falla tras 45s sin recibir nada (configurable) y continúa mientras llegan páginas, hasta 10 minutos; timeout REST de 15s, reconstrucción de la topología con debounce (2s) |
cluster/permissions.go | Sondeo de RBAC mediante SSAR (31 tipos de recursos), primero a nivel de clúster y después por namespace, semáforo de 10 |
cluster/optional_crds.go | Vuelve a comprobar los CRDs opcionales (cert-manager, Argo CD, VPA, políticas de Cilium) cada 2 minutos |
cluster/nslister.go | Wrappers de listers multinamespace para ServiceAccounts limitadas a namespaces |
cluster/graph.go | Grafo de topología en memoria |
cluster/relationships.go | Detección de aristas: ownerRefs, selectores, parentRefs de Gateway, volúmenes, referencias de entorno |
agent/channel | AgentChannel gRPC: ingesta de muestras, túneles para exec/port-forward/archivos |
metrics/collector.go | Consulta a Metrics Server (cada 30s), alternativa por namespace, degradación gradual |
insights/engine.go | Motor de evaluación de 24 reglas |
insights/policy.go | Clases de reglas, umbrales y la capa de políticas por regla |
insights/episodestore_bolt.go | Ciclo de vida de los episodios en BoltDB: episodios, transiciones, silencios, presencia |
insights/policystore_bolt.go | Ajustes de las políticas de reglas en BoltDB |
helm/ | Releases de Helm de solo lectura, decodificadas de sus Secrets de almacenamiento |
findings/ | Almacén de Security & Compliance: hallazgos de Trivy, Kyverno y Falco, persistidos para que respondan sin un conector en vivo |
copilot/ | Kobi: 41 herramientas, proveedores, conversaciones, memoria/compactación, analítica de uso |
mcp/ | Servidor MCP de solo lectura sobre Streamable HTTP y stdio |
auth/store.go, auth/jwt.go, auth/middleware.go | Usuarios y refresh tokens en BoltDB, emisión y verificación de JWT, aplicación de roles (viewer < editor < admin) |
auth/api_tokens_store.go | Tokens REST de larga duración (kbs_ de servicio, kbk_ de clave) con alcances por ruta y el rechazo en el borde público |
websocket/hub.go | Hub de difusión, búfer de 4096, descartes silenciosos cuando no hay clientes; las difusiones llevan una referencia (kind, namespace, name), nunca el objeto |
api/router.go | Router Chi con el middleware requireConnector |
Flujo de datos
- El Manager lee los contextos de kubeconfig + el registro persistente → conexión asíncrona (el servidor HTTP se enlaza de inmediato y devuelve 503 hasta que se conecta)
- Sondeo de permisos: llamadas SSAR, primero a nivel de clúster y después por namespace, ~2-5s
- Los informers arrancan solo para los recursos permitidos; las SAs limitadas a namespaces reciben factorías de informers por namespace con agregación de varios listers
- El LIST inicial de cada informer llega en páginas de 500 objetos; los watches
no cambian. Cada 5 minutos, una auditoría de la caché pide un objeto por tipo
y lee el conteo de
remainingItemCount, y se salta la pasada cuando el servidor no lo informa - La caché de Secrets deja fuera el almacenamiento de las releases de Helm: las listas y los conteos leen sus metadatos una vez por minuto, y el contenido de una release se lee cuando lo necesita una vista o un insight
- Una conexión que falla se reintenta tras 30 s, luego 1, 2 y 4 minutos, 5 como máximo; un agente que se reconecta o un cambio explícito de clúster lo intentan en el acto
- El cliente dinámico lista los recursos de Gateway API (timeout de 5s; si falla, se omiten sin error) y los CRDs opcionales bajo demanda
- Metrics Server se consulta cada 30s → caché en memoria; las muestras del
agente llegan a VictoriaMetrics y sirven
query/query_range(PromQL). Un lote que VictoriaMetrics rechaza por un motivo pasajero (error de conexión, timeout, 5xx, 429) se retiene, hasta 64 MiB, y se vuelve a escribir del más antiguo al más nuevo con sus propias marcas de tiempo, así que un reinicio de VictoriaMetrics no deja huecos - El motor de insights evalúa cada 60s sobre la caché de informers y las lecturas de Metrics Server, y persiste los episodios en BoltDB
- La API REST sirve recursos enriquecidos con las métricas inyectadas, paginados (50/página); WebSocket difunde los cambios, con reconstrucciones de la topología con debounce
Topología de despliegue
La interfaz web se puede servir desde un origen distinto al de la API (UI
y API separadas, con KUBEBOLT_CORS_ORIGINS listando el origen de la UI), y
el chart permite poner delante de la API un Ingress clásico o Gateway API
(gatewayAPI.enabled), con listeners separados para la API HTTP/WebSocket y
el canal gRPC del agente.