KubeBolt docs
ENES GitHub

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.

En esta página
  1. Qué necesita un backend autoalojado
  2. Qué funciona por el túnel
  3. Port-forward por HTTP

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:

  1. Los agentes llegan al puerto gRPC. El chart lo expone como el Service <release>-agent-ingest en el 9090. Hazlo accesible desde el clúster remoto con agentIngest.service.type (LoadBalancer o NodePort) o con la ruta de Gateway API (gatewayAPI.agent.*), y pon el host:port público en agentIngest.externalUrl (KUBEBOLT_AGENT_INGEST_URL): a partir de ahí el asistente lo usa como backendUrl del 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.
  2. 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).
  3. 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) en enforced, que sí necesita un reinicio. tokenreview solo funciona cuando el agente y el backend comparten clúster.
  4. El canal va cifrado: TLS en el backend (agentIngest.tls.*) o en el Gateway o balanceador de carga que tenga delante, y tls.enabled=true en 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:

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.