KubeBolt docs
ENES GitHub

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
  1. Diagrama del sistema
  2. Workspace de Go
  3. Las dos mitades
  4. Paquetes clave del backend
  5. Flujo de datos
  6. Topología de despliegue

Diagrama del sistema

ORIGEN Clúster(es) de Kubernetes
API Server
API principal de Kubernetes + CRDs
Metrics Server
metrics.k8s.io/v1beta1, uso en vivo
Agente de KubeBolt
opcional; conexión saliente por gRPC
Hubble · OpenCost · Prometheus
fuentes opcionales que lee el agente
MOTOR Backend de KubeBolt (Go)
Gestor de clústeres
ciclo de vida multiclúster, conexión asíncrona
Shared Informers
recursos tipados vía client-go
Dynamic Client
Gateway API + CRDs opcionales
Sonda de permisos
31 comprobaciones SSAR, semáforo de 10
Recolector de métricas
consulta a Metrics Server cada 30s
Agent Channel
ingesta gRPC + túneles de API, exec y archivos
Motor de insights
24 reglas, evaluadas cada 60s
Servicio de autenticación
sesiones JWT, viewer / editor / admin
REST API (Chi v5)
listas, detalles, YAML, logs
WebSocket Hub
difusión en tiempo real
Kobi (Copilot)
LLM multiproveedor, 41 herramientas
Almacenamiento
estado en BoltDB, histórico en VictoriaMetrics
INTERFAZ Frontend de KubeBolt (React 18 · TS · Vite 5 · Tailwind)
Vistas de recursos
26 vistas de lista, TanStack Table + Query
Cluster Map
React Flow 11, Grid · Flow · Traffic
Panel de Kobi
chat, llamadas a herramientas, propuestas de acción
Sistema de temas
oscuro/claro con variables CSS

Workspace de Go

Monorepo con go.work que contiene cuatro módulos:

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/.

PaquetePropósito
cluster/manager.goRegistro 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.goInformers 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.goSondeo 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.goVuelve a comprobar los CRDs opcionales (cert-manager, Argo CD, VPA, políticas de Cilium) cada 2 minutos
cluster/nslister.goWrappers de listers multinamespace para ServiceAccounts limitadas a namespaces
cluster/graph.goGrafo de topología en memoria
cluster/relationships.goDetección de aristas: ownerRefs, selectores, parentRefs de Gateway, volúmenes, referencias de entorno
agent/channelAgentChannel gRPC: ingesta de muestras, túneles para exec/port-forward/archivos
metrics/collector.goConsulta a Metrics Server (cada 30s), alternativa por namespace, degradación gradual
insights/engine.goMotor de evaluación de 24 reglas
insights/policy.goClases de reglas, umbrales y la capa de políticas por regla
insights/episodestore_bolt.goCiclo de vida de los episodios en BoltDB: episodios, transiciones, silencios, presencia
insights/policystore_bolt.goAjustes 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.goUsuarios y refresh tokens en BoltDB, emisión y verificación de JWT, aplicación de roles (viewer < editor < admin)
auth/api_tokens_store.goTokens 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.goHub 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.goRouter Chi con el middleware requireConnector

Flujo de datos

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.