KubeBolt docs
ENES GitHub

Primeros pasos

Conectar clústeres

Tres formas de conectar un clúster: kubeconfig, el agente de KubeBolt o solo métricas. El asistente Add cluster genera por ti el comando helm exacto.

En esta página
  1. Tipos de conexión
  2. Instalar el agente
  3. Fuentes de métricas
  4. Datos de costos (opcional)
  5. Actualizar
  6. Siguientes pasos

KubeBolt admite tres tipos de conexión, y puedes combinarlos libremente en tu flota. Conectar un clúster requiere el rol Admin. El botón es Add cluster en la página Clusters y Connect cluster en Fleet y Home (dónde está en la barra superior se explica en Home y Fleet):

Tipos de conexión

TipoCómo funcionaQué obtienes
KubeconfigKubeBolt lee todos los contextos del kubeconfig con el que se arrancó, o de uno que subas, y habla directamente con el API server. Una instalación dentro del clúster usa en su lugar su propia ServiceAccountRecursos en vivo, acciones (terminal, port-forward, escalar, editar…), insights, datos de Metrics Server. Nada que instalar en el clúster.
AgenteUn agente ligero corre en el clúster y se conecta de forma saliente a KubeBolt por gRPC; con rbac.mode=reader u operator, el backend llega al API server a través del túnel del agenteInventario en vivo, YAML, logs e insights aunque el API server no sea accesible desde KubeBolt, además de métricas históricas, flujos de red (Hubble) y datos de costos opcionales. Las acciones (exec, port-forward, escalar, borrar, editar) necesitan el modo operator.
Solo métricasEl agente corre con rbac.mode=metrics: envía métricas pero no lleva proxy de la APIPaneles e historial para clústeres de los que solo quieres telemetría; este agente no da inventario de recursos

Import kubeconfig solo funciona cuando el propio KubeBolt corre a partir de un kubeconfig (el binario único, Homebrew, krew, Docker o Compose) y con la autenticación activada. Una instalación dentro del clúster (el chart de Helm) y KubeBolt Cloud rechazan la subida con cannot add clusters in in-cluster mode: conecta sus otros clústeres con el agente. Se añaden todos los contextos del archivo subido; un contexto cuyo nombre ya existe tiene que renombrarse antes. Las credenciales tienen que funcionar desde donde corre el backend: un plugin exec como aws eks get-token necesita esa CLI dentro del contenedor.

Los clústeres conectados se guardan en un registro persistente: sobreviven a los reinicios, y cualquier clúster se puede renombrar o borrar desde la página Clusters (solo admin). Un clúster cuyo agente se detiene sigue en la lista, sin contacto y mostrando su último estado conocido, hasta que lo borres.

Instalar el agente

El agente se instala desde el registro OCI de Helm. Para un clúster remoto que se conecta a un backend autoalojado con un token de ingesta, define tres variables y ejecuta el resto tal cual:

export KB_TOKEN='kb_...'                          # del asistente o de Agent Tokens
export KB_BACKEND='agent.kubebolt.example.com:443' # host:puerto, sin esquema
export KB_CLUSTER='prod-eu'                        # cómo aparece en KubeBolt

kubectl create namespace kubebolt-system
kubectl -n kubebolt-system create secret generic kubebolt-agent-token \
  --from-literal=token="$KB_TOKEN"

helm install kubebolt-agent \
  oci://ghcr.io/clm-cloud-solutions/kubebolt/helm/kubebolt-agent \
  --namespace kubebolt-system \
  --set backendUrl="$KB_BACKEND" --set tls.enabled=true \
  --set auth.mode=ingest-token \
  --set auth.ingestToken.existingSecret=kubebolt-agent-token \
  --set cluster.name="$KB_CLUSTER" \
  --set rbac.mode=reader

El chart nunca ve el token en texto plano: lo lee del Secret que creas. Los tokens se emiten en Administration → Agents & Ingest → Agent Tokens, o desde el propio asistente, y se muestran una sola vez. Desde la 2.6.5, un token que un asistente te da para copiar deja de funcionar si ningún agente lo usa en 7 días; una vez que un agente lo ha usado, sigue funcionando. El asistente dice hasta cuándo, y Agent Tokens lo muestra. Un token que KubeBolt escribe directamente en el Secret del clúster no tiene ese plazo.

Usa el comando que genera el asistente en lugar de escribir esto a mano: hace referencia al Secret con tu token de ingesta, fija el nombre del clúster y lleva todas las opciones que activaste (modo RBAC, fuente de métricas, Hubble, OpenCost, TLS).

Comprueba que funcionó. Debería haber un pod del agente por nodo en Running, y el log debería mostrar channel registered en menos de un minuto:

kubectl -n kubebolt-system get pods -l app.kubernetes.io/name=kubebolt-agent
kubectl -n kubebolt-system logs ds/kubebolt-agent --tail=20

Después, el clúster aparece en el selector de clústeres y en Fleet, y Administration → Agents & Ingest → Activity muestra el agente. Si no aparece, consulta Solución de problemas.

A dónde se conecta el agente

backendUrl es un destino de conexión gRPC, host:port, nunca una URL con esquema:

KubeBolt corre…backendUrlTLS / autenticación
En el mismo clúster (release de Helm kubebolt en el namespace kubebolt)kubebolt-agent-ingest.kubebolt.svc.cluster.local:9090 (<release>-agent-ingest.<namespace>)TLS desactivado
Autoalojado, detrás del listener de agentes de Gateway API del chartagent.<your-domain>:443tls.enabled=true
Autoalojado, con el puerto del agente expuesto como LoadBalancer o NodePortesa dirección y ese puertoTLS solo si agentIngest.tls está activado
En tu máquina local (binario, Homebrew, krew, Docker), con el agente en kind, k3d, minikube o Docker Desktophost.docker.internal:9090 (en Linux, la dirección de tu máquina en la red de Docker)TLS desactivado
KubeBolt Cloudagent.kubebolt.io:443 (el asistente de Cloud lo rellena)tls.enabled=true, auth.mode=ingest-token

Para un clúster al que KubeBolt ya llega directamente (aquel en el que corre, o un contexto de kubeconfig), hay además un camino sin Helm: Administration → Agents & Ingest → Integrations → KubeBolt Agent → Install aplica el agente a través de la propia conexión de KubeBolt. Ese agente se gestiona desde el mismo panel, no con helm upgrade.

Exponer el puerto del agente

Un backend autoalojado escucha a los agentes en el puerto gRPC 9090 del Service <release>-agent-ingest, que es ClusterIP por defecto. El Ingress del chart no lo lleva. Para agentes de otros clústeres, elige una opción:

Después, define en el chart kubebolt:

ValorQué hace
agentIngest.externalUrlEl host:port público al que se conectan los agentes. El asistente lo rellena entonces y activa TLS y la autenticación por token
agentIngest.authModedisabled (por defecto) acepta cualquier agente que llegue al puerto; permissive autentica, registra los fallos y aun así acepta; enforced rechaza a los agentes sin un token válido. También en Administration → Agents & Ingest → Configuration (se aplica tras un reinicio)

Con el valor por defecto agentIngest.authMode=disabled, cualquiera que llegue al puerto del agente puede registrar un clúster y enviar métricas. Pon enforced antes de exponer el puerto fuera de una red de confianza.

Usa el chart de Helm. Los manifiestos sin procesar que hay en deploy/agent/ fijan el agente heredado 0.2.2 y se conservan solo como referencia; si necesitas manifiestos planos (entornos aislados, GitOps), genéralos desde el chart con helm template.

Modo RBAC

--set rbac.mode= elige el nivel de permisos de la ServiceAccount del agente. Tres valores, del más restringido al más amplio:

ModoAlcanceQué permite
metricsestadísticas del kubelet + list/watch de pods + get de namespacesSolo métricas y flujos de Hubble; ninguna llamada al apiserver pasa por el túnel. El clúster aparece como de solo métricas, y las vistas de recursos responden 503 cluster is monitored-only. Implica proxy.enabled=false.
reader (por defecto)get/list/watch en todo el clúster sobre */*Panel completo de solo lectura a través del túnel del agente; los verbos de escritura devuelven 403. Implica proxy.enabled=true.
operatorlectura + escritura sobre */*Exec, escalar, reiniciar, borrar y editar YAML desde el panel. En la práctica es cluster-admin para el agente, así que úsalo solo con un agente autenticado (auth.mode ingest-token o tokenreview): los asistentes lo rechazan sin token, el chart no lo comprueba. Implica proxy.enabled=true.

Tu rol de KubeBolt sigue aplicándose por encima: un Viewer no puede escalar nada, por mucho que el agente sí pueda.

Autenticación del agente

--set auth.mode= es la forma en que el agente le demuestra al backend quién es:

ModoCuándo
disabled (valor por defecto del chart)El backend acepta agentes sin autenticar (agentIngest.authMode disabled o permissive). Sirve junto al backend en una red de confianza
tokenreviewAgente en el mismo clúster que el backend: un token proyectado de ServiceAccount que el backend comprueba con la API TokenReview. Nada que emitir
ingest-tokenCualquier otro clúster, y siempre en KubeBolt Cloud: un token de Agent Tokens, leído del Secret indicado en auth.ingestToken.existingSecret

Fuentes de métricas

La opción de fuente de métricas del asistente (en Advanced) corresponde a estos valores del chart:

scrape.enabled y agent.promRead.enabled son mutuamente excluyentes: un agente tiene una única fuente canónica de muestras. El chart falla en helm template si los dos están activados.

Opciones avanzadas que ofrece el asistente: mTLS (CA + Secrets de cliente), anotaciones de ServiceAccount (IRSA / Workload Identity), node selector, tolerations, recursos, imagen y priority class, sobrescribir GOMEMLIMIT y extraEnv libre.

Datos de costos (opcional)

Para activar la pestaña Cost, dale al agente datos de OpenCost con cualquiera de los tres modos descritos en la documentación de costos, incluido un sub-chart de OpenCost integrado (opencost.enabled=true) si todavía no lo ejecutas. El OpenCost integrado necesita un Prometheus del que leer; el asistente te pide su URL. Usa una sola fuente de costo por agente: desde el agente 1.4.10, el chart rechaza agent.promRead.cost.enabled junto con el exportador de OpenCost.

Actualizar

El agente se versiona de forma independiente del backend (su propia línea 1.x; el chart 1.4.x va con el backend 1.10 y posteriores, incluido 2.x). Actualiza primero el backend y después el agente en cada clúster que tenga uno, con el contexto de kubectl de ese clúster:

helm upgrade kubebolt-agent \
  oci://ghcr.io/clm-cloud-solutions/kubebolt/helm/kubebolt-agent \
  -n kubebolt-system --reset-then-reuse-values

--reset-then-reuse-values (Helm 3.14+) conserva tus valores y toma los valores por defecto del chart nuevo; --reuse-values a secas conserva las imágenes fijadas del chart anterior. Usa el namespace en el que instalaste (helm list -A | grep kubebolt-agent). Un agente instalado desde Integrations no es una release de Helm: reinícialo (kubectl -n kubebolt-system rollout restart daemonset/kubebolt-agent) para que descargue la imagen nueva. Qué agente va con qué backend está en Compatibilidad. Desde la 2.7.0, la página Clusters avisa cuando conviene actualizar el agente de un clúster, con el comando (Multiclúster).

Siguientes pasos

Con los clústeres conectados, el resto de la documentación describe lo que puedes hacer con ellos, empezando por Home y Fleet: el panel, el motor de insights y Kobi. Si un clúster se niega a conectarse, empieza por Solución de problemas.