KubeBolt docs
ENES GitHub

Proyecto

Compatibilidad

Qué versión del agente va con qué backend, qué se rompe cuando no coinciden y qué versiones de Kubernetes y qué proveedores se admiten.

En esta página
  1. Backend y agente
  2. Cómo actualizar
  3. Qué cambió en el agente 1.0
  4. Versiones de Kubernetes
  5. Proveedores
  6. Notas de la versión

KubeBolt y kubebolt-agent se distribuyen como artefactos con versiones independientes: el agente tiene su propio chart, su propia imagen y su propio tag de versión. Están acoplados por exactamente un contrato: el esquema de métricas y etiquetas que emite el agente y que consumen las consultas del backend.

Versiones actuales: KubeBolt 2.7.0 (EE 2.7.1-e2), agente 1.4.10.

Backend y agente

KubeBoltAgenteEsquemaNotas
1.10.x – 2.7.x1.0.x – 1.4.xv1.0, canónico de PrometheusActual. Cualquier agente 1.x desde la 1.0 funciona con cualquier backend desde la 1.10. Nada de lo que depende el agente cambió de la 2.0 a la 2.7: el mismo esquema de métricas y etiquetas, y los agentes 1.4.1 a 1.4.10 no cambian ningún flag ni protocolo
1.10.x y posteriores0.2.xincompatibleEl agente emite el esquema heredado; las consultas del backend buscan los nombres canónicos. Paneles vacíos
1.9.x y anteriores1.0.xincompatibleAl revés. Paneles vacíos. No ejecutes esta combinación
1.9.x y anteriores0.2.xv0.x heredadoLos dos lados son previos al esquema canónico. Funciona, pero las funciones más nuevas (right-sizing P95, descartes de red, endpoints externos con FQDN) solo existen en la pareja canónica
1.5.x0.1.xinicialAnterior al RBAC de 3 niveles. Estable, pero sin agent-proxy ni flujos de Hubble

Así que la regla es corta: agente ≥ 1.0 con backend ≥ 1.10, y mantenlos en la misma generación. Las versiones 1.1 a 1.4 del agente son de fiabilidad, cardinalidad y obtención de datos de OpenCost sobre el mismo esquema: la 1.4.0 amplía la lista dropNetworkInterfaces por defecto, la 1.4.1 es un parche de seguridad, la 1.4.2 hace que el chart se instale en OpenShift sin configurar nada, la 1.4.3 informa su versión real, la 1.4.4 lleva el sidecar vmagent del chart a la v1.154.0, la 1.4.5 es una recompilación de seguridad, la 1.4.6 lleva vmagent a la v1.155.0, la 1.4.7 es una actualización de dependencias, la 1.4.8 lleva vmagent a la v1.156.0 y guarda la red de cada pod una sola vez, y la 1.4.9 olvida las claves de flujos de Hubble inactivas durante 15 minutos (sus series ya no solo crecen) y su scrape de node-exporter encuentra por defecto el node-exporter de kube-prometheus-stack, y la 1.4.10 envía solo las familias de OpenCost que lee KubeBolt y sube sus límites por defecto a 256Mi / 500m. Por eso, una actualización del agente dentro de la línea 1.x nunca depende de actualizar el backend. Un matiz con la 1.4.8: no envía red de pod para los pods con hostNetwork (su tráfico es el del nodo); el backend 2.6.0 representa la red de ese pod a partir de su nodo, y un backend más antiguo la muestra vacía.

Usa el chart del agente 1.4.10 con la imagen del agente 1.4.10, que es lo que viene por defecto. Desde la 1.4.2, la imagen declara un usuario numérico; en OpenShift, el chart 1.4.2 o posterior con una imagen más antigua fijada mediante image.tag no pasa la comprobación runAsNonRoot.

Desde la 2.7.0, KubeBolt avisa cuando el agente de un clúster está desactualizado. El agente 1.4.9 aparece como update available: existe la 1.4.10 y nada de la 1.4.9 necesita arreglo. Los agentes anteriores a la 1.4.9 aparecen como update recommended: por debajo de la 1.4.8 la red de cada pod se guarda dos veces, y por debajo de la 1.4.9, con los flujos de Hubble activados, las claves de flujo nunca se olvidan. KubeBolt nunca actualiza un agente por su cuenta; la página Clusters da los motivos y el comando (Multiclúster).

Una incompatibilidad no tumba nada. Los dos lados arrancan, el agente se registra y las muestras llegan al almacén de métricas. El único síntoma visible es que los paneles de ese clúster se muestran vacíos, y por eso se diagnostica mal como un problema de datos. Consulta Solución de problemas.

Detectar una incompatibilidad

Cuando un agente heredado se conecta a un backend actual, el backend escribe en su log, una vez por registro:

{
  "level": "WARN",
  "msg": "agent below minimum version — legacy schema",
  "agent_version": "0.2.2",
  "min_agent_version": "1.0.0",
  "hint": "upgrade kubebolt-agent helm chart to >=1.0.0; v0.x emits the legacy schema and dashboards will render empty"
}

La comprobación es fail-soft: el agente sigue conectándose y sigue enviando muestras. Un agent_version vacío o que no se puede interpretar no genera aviso, porque no todos los clientes lo envían.

Cómo actualizar

Actualiza primero el backend y después el agente en cada clúster que tenga uno, cada uno con el contexto de kubectl de ese clúster:

# 1. Dónde corre cada release y en qué versión está
helm list -A | grep kubebolt

# 2. Guarda una copia de los valores que configuraste
helm get values kubebolt -n kubebolt -o yaml > kubebolt-values.yaml

# 3. El backend
helm upgrade kubebolt \
  oci://ghcr.io/clm-cloud-solutions/kubebolt/helm/kubebolt \
  -n kubebolt --reset-then-reuse-values

# 4. El agente, en cada clúster que tenga uno
helm upgrade kubebolt-agent \
  oci://ghcr.io/clm-cloud-solutions/kubebolt/helm/kubebolt-agent \
  -n kubebolt-system --reset-then-reuse-values

Cada comando toma la versión más reciente; añade --version X.Y.Z para elegir una. Usa los namespaces que muestra helm list: el asistente Add cluster instala el agente en kubebolt-system, y el inicio rápido lo pone junto al backend en kubebolt. Un agente instalado desde la UI de KubeBolt (Administration → Agents & Ingest → Integrations → KubeBolt Agent) no es una release de Helm: ejecuta la imagen latest salvo que se eligiera un tag al instalarlo, así que kubectl -n kubebolt-system rollout restart daemonset/kubebolt-agent recoge la nueva.

Nunca uses --reuse-values entre versiones del chart. Conserva los valores por defecto del chart anterior, así que las imágenes que fija el chart (VictoriaMetrics, vmagent) se quedan en la etiqueta antigua, la que reemplazó una versión de seguridad, y un bloque de valores añadido desde entonces puede fallar al renderizarse. --reset-then-reuse-values (Helm 3.14+) parte de los valores por defecto del chart nuevo y aplica tus valores encima; un archivo de valores (-f) hace lo mismo.

Qué esperar. El pod de la API se reemplaza, no se actualiza de forma gradual, así que la UI no está disponible mientras arranca el pod nuevo; los agentes se reconectan solos y VictoriaMetrics se reinicia sobre el mismo volumen. Los usuarios, los ajustes, los clústeres registrados, el historial de insights y las conversaciones de Kobi viven en el volumen persistente del chart (activado por defecto) y sobreviven a la actualización. Cuando la nueva versión está en marcha, el chip Update desaparece de la barra superior.

Saltarse versiones. Lee la sección Upgrading de cada versión entre la tuya y la de destino (notas de la versión). En la 2.x, estas te piden algo:

VersiónQué revisar
2.0.0Actualiza el chart, no solo la imagen: el ClusterRole incorpora las reglas que necesitan los CRDs de los escáneres de seguridad
2.2.0Un host MCP configurado con un token de API Everything: sustitúyelo por uno MCP only
2.3.0api.resources fijado en tus valores: el límite de memoria por defecto del chart es ahora 1Gi (request de 128Mi), porque la API guarda en caché cada objeto Events que observa
2.4.0Un clúster cuyo agente se detiene sigue en la lista, sin contacto, hasta que lo borras. Los registros de agentes que la versión anterior dejó como «connected» empiezan a caducar
2.5.0copilot.maxTokens: 4096 en tus valores sigue cortando las respuestas largas: quítalo para usar el tope por modelo. Detrás de un firewall de salida, los conectores de nube de Kobi necesitan los endpoints que indican las notas
2.5.2OpenShift: la web corre con su propia ServiceAccount (<release>-web), que no necesita ninguna SCC
2.6.0Un VictoriaMetrics que gestiones tú necesita -maxLabelsPerTimeseries=60
2.6.1Un rol de conector de AWS creado antes necesita ecr:GetLifecyclePolicy y ecr:List* para las nuevas lecturas de ECR de Kobi (el panel lateral del conector muestra la política actualizada)
2.6.3RBAC que gestionas tú (rbac.create=false): concede get, list y watch sobre externalsecrets, secretstores y clustersecretstores (external-secrets.io), o Kobi no podrá leerlos. KubeBolt Cloud: en Approve & execute, cada cambio que hace Autopilot espera ahora a una persona
2.6.6Si fijaste tú la imagen del sidecar de Azure MCP Server (mcpConnectors.azure.sidecar.image, o una copia en un registro privado), súbela a 4.0.0-beta.6: la API habla con la 4.0.
2.6.7KUBEBOLT_AGENT_PROXY_CONNECT_TIMEOUT o KUBEBOLT_AGENT_PROXY_STUCK_TIMEOUT por debajo del timeout por petición + 5 s (35 s con los 30 s por defecto), en tus values o en Settings: la API lo sube y deja un aviso en el log; súbelo tú para quitar el aviso. El connect deadline pasa a 60s por defecto
2.7.0Una sola fuente de costo: una release del agente con agent.promRead.cost.enabled y el exporter de OpenCost a la vez (collectors.exporters.opencost, u opencost.enabled) hace fallar el helm upgrade a la 1.4.10 con un mensaje que nombra los dos; desactiva uno. Los límites del agente: los nuevos 256Mi / 500m se aplican salvo que tus values fijen resources (una copia completa del archivo de valores del chart lo hace); una ResourceQuota sobre límites en el namespace del agente necesita sitio para ellos. Tu propio scrape.metricRelabelConfigs sustituye la regex de keep del chart: añade las familias de costo que lista la del chart. Las series de OpenCost fuera de las 13 familias de costo y de sus kube_* (las familias de GPU, las métricas HTTP del propio OpenCost, pod_info, …) dejan de guardarse en cuanto se actualiza el backend, sea cual sea la versión del agente: una consulta tuya que las lea vuelve vacía

Revertir. helm history kubebolt -n kubebolt lista las revisiones; helm rollback kubebolt <REVISION> -n kubebolt restaura el chart y las imágenes anteriores. Lo que escribió la versión nueva se queda en los volúmenes.

En una flota, actualiza todos los agentes antes de dar por terminado el despliegue. Un despliegue parcial tiene arreglo (termínalo y la siguiente recarga vuelve a llenar los paneles), pero hasta entonces los clústeres rezagados muestran paneles vacíos y el backend registra un WARN por cada uno en cada reconexión. Después de dejar atrás un agente anterior a la 1.0, esto no imprime nada cuando ya no queda ninguno:

kubectl logs -n kubebolt deployment/kubebolt-api --tail=50 | grep "agent below minimum"

Qué cambió en el agente 1.0

El agente 1.0.0 renombró todas las métricas y etiquetas para seguir la convención de Prometheus para Kubernetes, el esquema de facto de cAdvisor, kube-state-metrics, node-exporter y Hubble. No hay doble emisión: el agente solo envía los nombres canónicos. Lo más destacado:

Los cambios mayores de esquema futuros suben a la vez la versión mayor del agente y la del backend. Las versiones menores y de parche del agente siguen siendo compatibles con la versión menor actual del backend: solo métricas y etiquetas nuevas, nunca renombrados.

Versiones de Kubernetes

VersiónSoporte
1.24 y posterioresCompleto
1.20 – 1.23Funciona con funciones degradadas. KubeBolt lee EndpointSlices de discovery.k8s.io/v1 y CronJobs de batch/v1, que solo existen desde la 1.21; en la 1.20, que no sirve ninguno de los dos, el insight de servicio sin endpoints no tiene nada que leer

Comprueba la tuya:

kubectl version -o json | jq -r .serverVersion.gitVersion

Proveedores

ProveedorMetrics ServerNotas
Amazon EKSNo viene instalado por defectoInstálalo (manifiesto o add-on de EKS): consulta la guía de EKS. Prometheus gestionado (AMP) compatible, con autenticación SigV4 mediante IRSA o Pod Identity
Google GKEPreinstaladoPrometheus gestionado (GMP) compatible, con Workload Identity
Azure AKSPreinstaladoPrometheus gestionado de Azure Monitor compatible, con Workload Identity
OpenShiftLo proporciona el clústerSe instala con la SCC restricted-v2 por defecto, sin soluciones provisionales, desde KubeBolt 2.3.0 y el agente 1.4.2. Las versiones anteriores necesitan las soluciones provisionales de la guía de OpenShift, que también cubre el único punto que sigue abierto
k3s / k0sPreinstaladoFunciona sin configurar nada
kubeadmInstalación manualkubectl apply -f del manifiesto de la versión de metrics-server
Docker DesktopInstalación manualConsulta la guía de Docker Desktop
MinikubeAddonminikube addons enable metrics-server
kind / k3dInstalación manualPuede necesitar --kubelet-insecure-tls. Ten en cuenta la advertencia sobre Falco: los «nodos» comparten un mismo kernel

La versión 1.10 se validó en GKE con Dataplane V2, EKS, AKS y GKE con Calico OSS.

Metrics Server es recomendable, no obligatorio. Sin él, las barras de asignación en vivo de Overview muestran «no data»; todo lo demás, incluidas la CPU y la memoria históricas a través del agente, sigue funcionando.

Notas de la versión

Las notas de cada versión se publican en GitHub releases, y el agente mantiene su propio changelog en el mismo repositorio. Consulta el Historial de cambios.