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
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):
- Mientras no hay ningún clúster conectado, abre el asistente del primer clúster: pones nombre al clúster (en autoalojado, también confirmas la dirección a la que se conecta el agente), pegas un bloque de instalación y espera hasta que el agente reporta. Su enlace Advanced setup lleva a todas las opciones de abajo, reutilizando el token y el nombre del asistente en lugar de emitir un segundo token, y Back to the simple setup vuelve a él; el recorrido de Cloud está en Primeros pasos en Cloud.
- Cuando ya hay un clúster, abre un menú con dos caminos: Install agent
(recomendado), un asistente que imprime el comando
helmfinal con todo lo que seleccionaste, e Import kubeconfig, para un clúster cuyo API server es accesible desde este backend.
Tipos de conexión
| Tipo | Cómo funciona | Qué obtienes |
|---|---|---|
| Kubeconfig | KubeBolt 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 ServiceAccount | Recursos en vivo, acciones (terminal, port-forward, escalar, editar…), insights, datos de Metrics Server. Nada que instalar en el clúster. |
| Agente | Un 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 agente | Inventario 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étricas | El agente corre con rbac.mode=metrics: envía métricas pero no lleva proxy de la API | Paneles 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… | backendUrl | TLS / 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 chart | agent.<your-domain>:443 | tls.enabled=true |
| Autoalojado, con el puerto del agente expuesto como LoadBalancer o NodePort | esa dirección y ese puerto | TLS solo si agentIngest.tls está activado |
| En tu máquina local (binario, Homebrew, krew, Docker), con el agente en kind, k3d, minikube o Docker Desktop | host.docker.internal:9090 (en Linux, la dirección de tu máquina en la red de Docker) | TLS desactivado |
| KubeBolt Cloud | agent.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:
- Gateway API:
gatewayAPI.enabled=truecongatewayAPI.agent.host=agent.example.comañade un listener TLS en el 443 con unaGRPCRoutehacia el puerto del agente (consulta Métodos de instalación). Si un CDN hace de proxy de tu DNS, deja ese hostname en modo solo DNS: los proxies rompen el gRPC bidireccional de larga duración. - LoadBalancer o NodePort:
--set agentIngest.service.type=LoadBalancer, oNodePortcon unagentIngest.service.nodePortfijo. Esto es gRPC en claro salvo que también definasagentIngest.tls.enabled=trueyagentIngest.tls.existingSecret(un Secret contls.crtytls.key).
Después, define en el chart kubebolt:
| Valor | Qué hace |
|---|---|
agentIngest.externalUrl | El 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.authMode | disabled (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:
| Modo | Alcance | Qué permite |
|---|---|---|
metrics | estadísticas del kubelet + list/watch de pods + get de namespaces | Solo 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. |
operator | lectura + 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:
| Modo | Cuá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 |
tokenreview | Agente 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-token | Cualquier 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:
- None — kubelet metrics only (siempre activo): estadísticas del kubelet y
señales de los nodos que recoge el DaemonSet del agente; añade
hubble.enabled=truepara los flujos de Cilium Hubble. - Scrape annotated pods (
scrape.enabled=true): un sidecarvmagentincluido hace scraping de los pods con la anotaciónprometheus.io/scrape: "true"y envía las muestras a KubeBolt, con límites defensivos de cardinalidad; el descubrimiento de node-exporter y kube-state-metrics es opcional (scrape.discovery.nodeExporter.enabled,scrape.discovery.kubeStateMetrics.enabled). Envía porremote_write, no por el canal gRPC, así que necesitascrape.remoteWriteUrlapuntando al receptor del backend (http://kubebolt-api.kubebolt.svc.cluster.local:8080/api/v1/prom/writepara la releasekubeboltdentro del clúster), y el backend tiene que aceptarremote_write(metrics.remoteWrite.enabled=trueen el chartkubebolt, o Administration → Agents & Ingest → Configuration). El comando del asistente no incluyescrape.remoteWriteUrl: añádelo tú, o vmagent entra en crash-loop. - Read from existing Prometheus (
agent.promRead.enabled=true): en lugar de hacer scraping, un Deployment aparte del agente, de una sola réplica, consulta la APIquery_rangede tu Prometheus. Este es el camino para Prometheus gestionado: Amazon Managed Prometheus, Google Managed Prometheus y Azure Monitor, con autenticación por proveedor (none,basicAuth,bearer,awsSigV4vía IRSA,gcpIamvía Workload Identity,azureWorkloadIdentity).
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.