Configuración
Clústeres remotos
Opera clústeres a los que KubeBolt no llega directamente: el agente del clúster se conecta hacia fuera y nada entra. Exec, port-forward y el explorador de archivos funcionan por el túnel.
No todos los clústeres son accesibles desde donde corre KubeBolt: control planes privados de GKE/EKS, clústeres detrás de un bastión o redes sin ninguna ruta entrante. En el modo agent-proxy, un agente dentro del clúster abre una conexión saliente hacia el backend de KubeBolt y canaliza las operaciones de vuelta por ella. Nada se conecta hacia dentro: ni API server expuesto, ni agujeros en el firewall, ni VPN.
Pocas veces escribes esta configuración a mano: tanto en la edición open source como en KubeBolt Cloud, el asistente Add cluster genera el comando de instalación del agente para tu modo de conexión; lo pegas una vez y el túnel queda levantado.
Qué necesita un backend autoalojado
En KubeBolt Cloud esto ya está resuelto. En tu propio backend, el asistente se encarga del lado del agente una vez que se cumplen cuatro condiciones:
- Los agentes llegan al puerto gRPC. El chart lo expone como el Service
<release>-agent-ingesten el 9090. Hazlo accesible desde el clúster remoto conagentIngest.service.type(LoadBalanceroNodePort) o con la ruta de Gateway API (gatewayAPI.agent.*), y pon elhost:portpúblico enagentIngest.externalUrl(KUBEBOLT_AGENT_INGEST_URL): a partir de ahí el asistente lo usa comobackendUrldel agente y propone por defecto TLS y un token de ingesta. Una CDN delante de ese host rompe el gRPC bidireccional: déjalo en modo solo DNS. - El autorregistro está activado; si no, el clúster remoto envía métricas pero nunca aparece en el selector. El chart de Helm lo activa; con el binario o Docker Compose, actívalo en Administration → Agents & Ingest → Configuration (sin reiniciar).
- Los agentes se autentican. Emite un token de ingesta en Administration →
Agents & Ingest → Agent Tokens e instala el agente con
auth.mode=ingest-token; después pon el modo de autenticación de agentes del backend (agentIngest.authMode,KUBEBOLT_AGENT_AUTH_MODE) enenforced, que sí necesita un reinicio.tokenreviewsolo funciona cuando el agente y el backend comparten clúster. - El canal va cifrado: TLS en el backend (
agentIngest.tls.*) o en el Gateway o balanceador de carga que tenga delante, ytls.enabled=trueen el agente.
Las variables detrás de cada uno de estos puntos están en Variables de entorno.
Qué funciona por el túnel
No se trata de un espejo de solo lectura. La operación completa funciona contra un backend remoto:
- Terminal / exec: abre una shell en un contenedor.
- Port-forward: llega a un servicio que corre en el clúster remoto.
- Explorador de archivos: navega y lee archivos dentro de un contenedor.
Lo que puede hacer el túnel depende del rbac.mode del agente: reader da un
panel completo de solo lectura, y exec, escalar, reiniciar, borrar y editar YAML
necesitan operator (consulta RBAC). Tu
rol en KubeBolt sigue aplicándose por encima.
Cada respuesta de la API cruza el túnel a través del agente, que guarda cada una entera. KubeBolt pide las listas en páginas de 500 objetos y, desde el agente 1.4.10, un cuerpo que supera una cuarta parte del límite de memoria del agente se responde con un error en lugar de un OOMKill. En un clúster con miles de objetos, dale más memoria al agente: consulta El agente.
Port-forward por HTTP
Los port-forwards usan el stream SPDY de client-go, y en los clústeres con
agent-proxy ese stream SPDY viaja dentro del AgentChannel gRPC del agente. Se
expone a través de un proxy inverso HTTP en /pf/{id}/, para que el panel
pueda abrir un servicio redirigido sin acceso de red directo al backend. Un
túnel (exec, port-forward o explorador de archivos) se cierra tras 5 minutos
sin tráfico (KUBEBOLT_AGENT_TUNNEL_IDLE_TIMEOUT).
Por debajo, POST /portforward sí abre un listener TCP real, en el host del
backend, a través de client-go: eso es lo que /pf/{id}/ canaliza. Lo que no
existe es un endpoint TCP en bruto accesible desde tu máquina: salvo que ya
puedas enrutar hasta la red del backend, un cliente de base de datos no tiene a
qué conectarse. Lo que se ofrece es la ruta HTTP.
Limitaciones conocidas. Las apps que fijan en el código rutas raíz
absolutas (/static, /api) no se mostrarán bien a través de /pf/{id}/ sin
configurar una subruta en la propia app, por ejemplo el root_url de Grafana.
Y como la superficie expuesta es HTTP, no se puede llegar por ella a un
protocolo que no sea HTTP (Postgres, MySQL, Redis): el reenvío TCP en bruto
hacia tu máquina no está disponible.
La ruta HTTP remota se ha validado de extremo a extremo por internet, a través de un proxy inverso Caddy con TLS, con el agente operator corriendo en un clúster distinto del backend.