Configuración
El agente
El agente opcional, solo de conexiones salientes, que habilita las métricas históricas, los flujos de red, los costos y el acceso a clústeres remotos.
En esta página
KubeBolt funciona solo con un kubeconfig. El agente es el siguiente paso opcional: un componente ligero que instalas en un clúster para habilitar las métricas históricas, los flujos de red de Hubble, los datos de costos y, para los clústeres a los que KubeBolt no llega, el túnel por el que viajan sus llamadas a la API. Se conecta solo hacia fuera por gRPC: el API server del clúster nunca queda expuesto, y eso es lo que hace viables los clústeres privados, detrás de un firewall o con la salida restringida.
El chart ejecuta hasta dos workloads, que se configuran en el asistente Add cluster:
- DaemonSet (siempre): recoge las estadísticas del kubelet y de cAdvisor, y
la carga y la presión de cada nodo, y las envía al almacén de métricas de
KubeBolt. Un pod del clúster, elegido mediante un Lease, también lee los
flujos de Hubble (
hubble.enabled=true, desactivado por defecto) y hace scraping de exporters adicionales como OpenCost. Conrbac.mode=readeruoperator, el DaemonSet también transporta el túnel que permite a KubeBolt llegar a la API del clúster. - Deployment
promread(cuandoagent.promRead.enabled=true): una sola réplica, añadida junto al DaemonSet, que lee las familias de métricas que el DaemonSet no produce (kube-state-metrics, carga y presión de los nodos, errores de disco y de red) de un Prometheus que ya tengas, incluidas las ofertas gestionadas (AMP, GMP, Azure Monitor) con autenticación por proveedor (basic, bearer, AWS SigV4, GCP IAM, Azure Workload Identity). Consulta Métricas.
El chart
El agente se distribuye como su propio chart OCI, que el asistente genera con los valores correctos:
helm install kubebolt-agent \
oci://ghcr.io/clm-cloud-solutions/kubebolt/helm/kubebolt-agent \
--namespace kubebolt-system --create-namespace \
--set backendUrl=kubebolt-agent-ingest.kubebolt.svc.cluster.local:9090
Valores principales (consulta el values.yaml del chart para la referencia
completa y comentada):
| Valor | Por defecto | Para qué sirve |
|---|---|---|
backendUrl | (ninguno, obligatorio) | Dónde se conecta el agente con su backend: un destino de conexión gRPC con la forma <host:port>, sin esquema. Dentro del clúster es el Service <release>-agent-ingest del chart de KubeBolt en el 9090, no el Service web |
cluster.name / cluster.id | (ninguno) / el UID de kube-system | Cómo se registra y se muestra el clúster en KubeBolt |
rbac.mode | reader | Cuánto puede hacer la ServiceAccount del agente: metrics, reader u operator (detalles). reader y operator activan el túnel. Ejecuta operator solo con auth.mode configurado; el chart no lo impone |
auth.mode | disabled | Autenticación con el backend: disabled, tokenreview (mismo clúster que el backend) o ingest-token (emitido en la UI de administración; obligatorio entre clústeres y en Cloud), con el token en auth.ingestToken.existingSecret |
tls.* | desactivado | TLS de transporte y mTLS opcional (paquete de CA, certificado de cliente, cambio del SNI) |
hubble.* | desactivado | Recogida de flujos de red desde un relay de Hubble existente, con su dirección y TLS |
collectors.* | (ninguno) | Ajusta qué se recoge: dropNetworkInterfaces, exporters adicionales |
opencost.* | desactivado | Instala el subchart de OpenCost y hace scraping de él. Para un OpenCost que ya tengas, añádelo en collectors.exporters (detalles). Cualquiera de los dos junto con agent.promRead.cost.enabled hace fallar el render: una sola fuente de costo |
agent.promRead.* | desactivado | Modo promread: url del endpoint, auth por proveedor, cost.enabled opcional y deployment.* para los recursos y la planificación (scheduling) de ese pod |
agent.deferNodeStress / agent.deferNodeNetwork | false | Deja la carga/PSI, o la red del nodo, a un node-exporter al que ya haces scraping |
scrape.* | desactivado | Sidecar de scrape vmagent opcional, con controles de relabeling y de descubrimiento |
serviceAccount.annotations | (ninguno) | Identidad de nube para promread: el rol de IRSA o el binding de Workload Identity |
resources | 10m/64Mi solicitados, 500m/256Mi de límite (100m/128Mi antes de la 1.4.10) | Por pod del DaemonSet. Las requests siguen siendo pequeñas para que el agente quepa en nodos cargados. Los límites dejan sitio para las respuestas del API server que retransmite el agente: consulta Memoria en un clúster grande |
tolerations / nodeSelector / affinity | tolera todos los taints | Dónde corre el DaemonSet. Restringe tolerations para mantenerlo fuera de pools dedicados |
priority.* | desactivado | Una PriorityClass para que el agente pueda desalojar pods en nodos llenos |
gomemlimit | 90% del límite de memoria de cada contenedor | Fija en su lugar un objetivo de memoria de Go explícito |
logLevel | info | debug, info, warn, error |
image.tag | la versión del chart | Fija la imagen del agente |
extraEnv | [] | Variables del agente que no tienen un valor propio |
Versionado
El agente sigue su propio ritmo de versiones (ahora mismo, la línea 1.4.x) sobre un esquema de métricas y etiquetas v1.0 estable. El esquema es el único contrato entre los dos lados, así que cualquier agente 1.x ≥ 1.0 funciona con cualquier backend de KubeBolt ≥ 1.10: actualiza cualquiera de los dos por separado dentro de esos límites. El agente 0.2.x emite el esquema previo al canónico y muestra paneles vacíos contra un backend moderno; el backend registra un WARN en el log cuando se conecta uno.
promRead es el único modo con una ventana más estrecha: llegó en el
agente 1.1.0 junto con el backend 1.13.0. Sus muestras siguen llegando
al almacén de métricas en los backends 1.10–1.12, pero la tarjeta de
integración Prometheus (read) no se muestra ahí. Es un mínimo para un modo, no
para el agente. La matriz completa, en Compatibilidad.
El changelog propio del agente recoge cada versión de su línea, sin las versiones del backend intermedias: packages/agent/CHANGELOG.md.
Actualiza con --reset-then-reuse-values (o con un archivo de valores) en lugar
de --reuse-values, que conserva los valores por defecto del chart anterior,
incluida la etiqueta de imagen del sidecar vmagent. Los pasos, en
Compatibilidad → Cómo actualizar.
Desde la 2.7.0, KubeBolt avisa cuando el agente de un clúster está
desactualizado, y lo juzga por el más antiguo de sus agentes conectados:
Clusters, Fleet y Home lo muestran, y Kobi responde con el mismo
comando helm upgrade. KubeBolt nunca ejecuta ese comando: el agente es tu
release de Helm, a menudo gestionada con GitOps, y actualizarlo desde KubeBolt
exigiría permisos de escritura sobre su DaemonSet. Consulta
Multiclúster.
Postura de seguridad: conexiones solo salientes (gRPC, más HTTP
remote_write cuando el sidecar de scrape está activo), sin puertos
entrantes, se ejecuta como no root con un sistema de archivos raíz de solo
lectura y, en configuraciones entre clústeres, se autentica con un token de
ingesta de alcance limitado. Las métricas pasan por el backend: el agente
nunca escribe directamente en el almacén de métricas.
Memoria en un clúster grande
En un clúster conectado a través de él (rbac.mode=reader u operator), el
agente retransmite las respuestas del API server y guarda cada una entera
mientras la envía. El backend pide las listas en páginas de 500 objetos, pero
la primera conexión de un clúster grande sigue pasando decenas de MB por el
agente.
- Valores por defecto desde la 1.4.10:
256Mide límite de memoria y500mde CPU. Con128Mi, el agente terminaba en OOMKilled en un clúster con miles de ReplicaSets, y con100mla primera conexión de un clúster grande se quedaba sin CPU (throttling). El Deploymentpromreadmantiene sus propios límites. - Una respuesta demasiado grande es un error, no un OOMKill. Cada cuerpo
retransmitido tiene un tope de una cuarta parte del límite de memoria del
contenedor, y nunca por encima de los 63 MiB del canal. Si lo supera, el
agente responde con un error que nombra el tope, el límite y
resources.limits.memory. - En un clúster con miles de objetos, sube el límite en la release del
agente:
--set resources.limits.memory=512Mi. Cuando un pod del agente termina en OOMKilled o se mantiene cerca de su límite, los insights OOMKilled y Memory Near Limit dan elhelm upgradeque lo sube.