KubeBolt docs
ENES GitHub

Primeros pasos

Solución de problemas

Síntoma, causa y solución para los fallos que ocurren de verdad: pods atascados en Pending, paneles vacíos, el banner de acceso limitado, errores 503, Cluster unreachable, una contraseña de admin perdida y un agente que no llega al backend.

En esta página
  1. Los pods se quedan en Pending tras helm install
  2. El agente está conectado pero los paneles están vacíos
  3. Banner ámbar: “Limited access — N of M resource types restricted by RBAC”
  4. 503 “cluster not connected” justo después de cambiar de clúster o de reiniciar
  5. ”Cluster unreachable” en un clúster que sí es accesible
  6. ”No contact with this cluster” o “Waiting for the agent”
  7. El agente no llega al backend
  8. El agente termina en OOMKilled en un clúster grande
  9. Contraseña de admin perdida
  10. La terminal no se abre en un clúster conectado por agente
  11. No aparece el panel de Kobi
  12. Si sigues sin solución

Busca tu síntoma. Cada entrada dice qué ves, por qué ocurre y qué hacer. Los comandos asumen la release de Helm kubebolt en el namespace kubebolt y el agente en kubebolt-system; usa los tuyos (helm list -A | grep kubebolt). Los fallos propios de cada escáner tienen su propia página: Trivy, Kyverno, Falco.

Los pods se quedan en Pending tras helm install

Síntoma. helm install --wait agota el tiempo de espera, y kubebolt-api-… y kubebolt-victoriametrics-0 se quedan en Pending.

Causa. El chart crea dos PersistentVolumeClaims (10 GiB para VictoriaMetrics y 1 GiB para los datos propios de KubeBolt) en la StorageClass por defecto del clúster. Si no hay ninguna por defecto (EKS sin el driver EBS CSI, algunos clústeres bare-metal), nunca se vinculan.

Solución.

kubectl -n kubebolt get pvc
kubectl get storageclass

Instala un aprovisionador (en EKS, el complemento del driver EBS CSI) y marca una StorageClass como predeterminada, o indica una explícitamente con --set metrics.storage.embedded.persistence.storageClass=<class> y --set auth.persistence.storageClass=<class>.

El agente está conectado pero los paneles están vacíos

Síntoma. El clúster aparece como conectado, el pod del agente está Running, y aun así los paneles de historial salen en blanco.

Causa y solución, en el orden en que conviene comprobarlas:

ComprobaciónCómo se veSolución
Agente anterior a la 1.0El log de la API muestra agent below minimum version — legacy schema, con agent_version y min_agent_versionActualiza el agente (más abajo)
El almacén de métricas está caídoTodos los paneles de historial están vacíos en todos los clústeres; Administration → System → Health muestra que VictoriaMetrics no reportakubectl -n kubebolt get pods,pvc; consulta la entrada anterior si su PVC está en Pending
Un límite está recortando la ingestaUn banner en Overview: Ingestion truncated by plan limits o Metric series cap engagedEn Cloud, los límites del plan (Free: 10 nodos, 150 pods, 25.000 series); lo que los supera no se registra. En autoalojado, sube los límites de series en Administration → Agents & Ingest → Configuration
Solo han pasado unos minutosSe ven los valores en vivo, pero todavía no el historialEspera: el historial necesita que el agente envíe unos minutos de muestras

La discrepancia de esquema es la difícil de detectar. El agente y el backend se publican como artefactos con versiones independientes, unidos por un único contrato: los nombres de métricas y etiquetas que el agente emite y el backend consulta. Cuando no coinciden, las muestras siguen llegando al almacén de métricas y las consultas simplemente no encuentran nada. Nada se cae. Compruébalo:

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

Actualiza el agente por encima de la versión mínima y la siguiente recarga vuelve a llenar los paneles:

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

Si ese grep no devuelve nada y los paneles siguen vacíos tras las demás comprobaciones, puede que la discrepancia vaya en sentido contrario: un agente actual frente a un backend anterior a la 1.10. Consulta la matriz en Compatibilidad.

En una flota, esto va por clúster. Un backend que atiende una mezcla de agentes actuales y desfasados muestra paneles vacíos solo en los clústeres que se han quedado atrás, y registra un WARN por cada agente heredado en cada reconexión.

Síntoma. Una franja de aviso bajo la barra superior, y listas de recursos a las que les faltan tipos enteros. Los tipos restringidos aparecen atenuados con un icono de escudo en la barra lateral.

Causa. La sonda de permisos se ejecutó y encontró que las credenciales con las que se conecta KubeBolt no pueden hacer list/watch sobre algunos tipos de recurso: un usuario de kubeconfig con un RBAC más restringido, el chart kubebolt instalado con rbac.create=false y un rol propio más restringido, o un agente cuyo ClusterRole se editó a mano.

Solución. Comprueba qué se sondeó (GET /api/v1/cluster/permissions devuelve el resultado completo de la sonda) y después amplía el rol que hay detrás de esas credenciales. En el caso de un agente, volver a aplicar el nivel del chart restaura su ClusterRole:

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

Los niveles del agente se describen en Conectar clústeres y en RBAC. Un agente en rbac.mode=metrics no muestra este banner: su clúster es solo de métricas, y las vistas de recursos responden 503 cluster is monitored-only. Una CRD opcional ausente (políticas de Cilium, aplicaciones de Argo CD, certificados de cert-manager) tampoco cuenta para este banner y genera en su lugar un aviso aparte, neutro. El banner se puede descartar; descartarlo no cambia ningún permiso.

Dos casos relacionados. Los tipos que KubeBolt solo puede leer namespace por namespace se quedan sin acceso cuando listar los namespaces sigue fallando, y las vistas lo indican en lugar de mostrar una lista parcial (RBAC). Sin acceso a los eventos, la página Events muestra Access Restricted, GET /events responde 403 y a Kobi se le indica que no ver eventos no significa que no los haya.

503 “cluster not connected” justo después de cambiar de clúster o de reiniciar

Síntoma. Las peticiones fallan con 503 cluster not connected durante unos segundos después de cambiar de clúster o de reiniciar el backend. (Kobi sigue respondiendo en ese intervalo, sobre KubeBolt y Kubernetes, pero sus herramientas de clúster no tienen nada que leer hasta que el conector esté listo.)

Causa. El conector todavía está en fase de calentamiento. Una conexión en frío construye las cachés de los informers para cada tipo de recurso observado y no sirve lecturas hasta que se sincronizan. El margen es el Cluster connect timeout, el tiempo que la sincronización puede pasar sin recibir nada: 45 segundos por defecto, en Administration → System → General (5–600 s, se aplica en la siguiente conexión), o KUBEBOLT_CACHE_SYNC_TIMEOUT_SECONDS al arrancar. Una sincronización que sigue recibiendo páginas continúa, hasta 10 minutos. Mientras tanto, la página muestra los pasos y una barra que sigue los datos que faltan por llegar (Multiclúster).

Solución. Espera. Es un estado de arranque, no un error, y el pool de conectores en caliente hace que los cambios posteriores sean instantáneos. Hay otros dos cuerpos de respuesta 503 que no son de calentamiento:

Si nunca se resuelve, lee la siguiente entrada.

”Cluster unreachable” en un clúster que sí es accesible

Síntoma. La página muestra Cluster unreachable (“Could not connect to the selected cluster”), mientras que kubectl contra el mismo clúster funciona. Después de un intento fallido, la API espera 30 segundos, luego 1, 2 y 4 minutos, 5 como máximo, antes de volver a conectar, y la página de carga y el 503 dicen cuándo será el siguiente intento; cambiar a ese clúster lo intenta en el acto. El log de la API dice por qué, con una línea cluster runtime failed to connect por intento:

kubectl -n kubebolt logs deployment/kubebolt-api | grep -iE "failed to connect|staying disconnected|stopped|timed out"

Causa. La conexión no recibió nada del clúster durante más tiempo que su margen, o seguía en curso a los 10 minutos. El margen que aplica depende de cómo llega KubeBolt al clúster:

Acceso…ErrorMargen
Directo (dentro del clúster, kubeconfig)cache sync stopped: no response from the cluster for 45s — cluster may be unreachableCluster connect timeout: 45 s por defecto
A través de un agenteconnect to context … stopped: no response from the cluster for 60s — agent may be stuckConnect deadline: 60 s por defecto (25 s antes de la 2.6.7)

Antes de la 2.6.5 ambos eran plazos fijos (timed out waiting for cache sync, connect timed out after 25s): un clúster grande que seguía recibiendo páginas fallaba en el mismo punto en cada intento. Actualizar resuelve ese caso sin subir nada.

En un clúster accesible, el culpable habitual es una única colección enorme: los Events. KubeBolt espera a todos los informers antes de servir cualquiera, así que un informer lento retiene al resto. Lo reprodujimos en OpenShift 4.20 / Kubernetes 1.33.6: GET /api/v1/events devolvió ~138 MiB, mientras que Nodes y Deployments estaban listos en ~1,8 s y aun así no se podían servir.

Solución. Confirma primero el tamaño:

kubectl get events -A --no-headers | wc -l

Después, en este orden:

Hay más detalle en OpenShift, donde se reprodujo por primera vez. No es exclusivo de OpenShift: cualquier clúster con mucho movimiento puede toparse con ello.

”No contact with this cluster” o “Waiting for the agent”

Síntoma. Una franja ámbar, “No contact with this cluster since …”, sobre páginas que muestran el último estado conocido del clúster, o un indicador de carga, “Waiting for the agent”, en lugar de la página.

Causa. KubeBolt llega a este clúster a través de su agente, y no hay ningún agente conectado. Justo después de reiniciar KubeBolt, los agentes se vuelven a conectar en menos de un minuto. Si no lo hacen, se cayó el agente, su nodo o la red; KubeBolt no puede saber cuál desde su lado.

Solución. En ese clúster, revisa el agente (kubectl -n kubebolt-system get pods y sus logs; consulta la siguiente entrada). Si diste de baja el clúster, elimínalo desde Clusters: un clúster cuyo agente se detiene sigue en la lista hasta que lo hagas.

El agente no llega al backend

Síntoma. El pod del agente se ejecuta (o nunca arranca) y el clúster no aparece nunca, o el asistente Add cluster se queda esperando.

Empieza por aquí, con kubectl apuntando al clúster del agente:

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

Un agente sano registra dialing backend y después channel registered. Un intento fallido registra shipper session ended, will reconnect con el error, y reintenta con espera progresiva (backoff). Causas y soluciones, en el orden en que conviene comprobarlas:

ComprobaciónCómo se veSolución
Clúster equivocadoNada en kubebolt-systemkubectl apuntaba a otro contexto. Cambia de contexto y vuelve a ejecutar la instalación
Falta el Secret del tokenPods atascados en ContainerCreating; kubectl describe pod dice secret "kubebolt-agent-token" not foundCrea el Secret en el namespace del agente, con el token bajo la clave token y el nombre indicado en auth.ingestToken.existingSecret
El chart se niega a renderizarbackendUrl is required, o auth.mode=ingest-token requires auth.ingestToken.existingSecretDefine el valor que falta
backendUrl lleva esquemaErrores de conexión o de dirección en el logEs un destino de conexión gRPC (dial target), host:port, sin https://
Dirección o puerto equivocadosconnection refusedEl Service <release>-agent-ingest de un backend autoalojado escucha en 9090; detrás del listener de Gateway API o de un balanceador con TLS suele ser 443. El de KubeBolt Cloud es agent.kubebolt.io:443
Salida bloqueadaTimeoutsEl agente solo abre conexiones salientes. Permite el tráfico de salida hacia el host y el puerto del backend
TLS no coincideErrores de handshake TLS, o la conexión se cierra antes del primer mensaje--set tls.enabled=true para cualquier endpoint que termine TLS (normalmente 443), y desactivado para un 9090 sin TLS
Token rechazadocode = Unauthenticated desc = agent auth: invalid credentialsToken ausente, mal escrito o caducado, frente a un backend que exige autenticación de agentes (Cloud siempre la exige). Emite un token nuevo en Administration → Agents & Ingest → Agent Tokens, reemplaza el Secret y después ejecuta kubectl -n kubebolt-system rollout restart ds/kubebolt-agent
Token revocadocode = PermissionDenied desc = agent auth: credential rejectedLa misma solución: un token nuevo
Límite del plan (Cloud)code = ResourceExhausted desc = cluster cap reached (2/2) for plan "free" — remove a cluster or upgrade to add anotherElimina en Clusters un clúster que ya no uses, o cambia de plan en Administration → Billing

Después confirma que el backend recibió algo: Administration → Agents & Ingest → Activity muestra muestras por segundo, series activas, eventos de conexión (si hay un recuento de auth rejected, es el token) y una lista de los agentes conectados en este momento. Si tu agente no está en esa lista y no se rechazó nada, el tráfico nunca llegó al backend: es un problema de red o de dirección, no de autenticación.

El agente termina en OOMKilled en un clúster grande

Síntoma. En un clúster conectado a través de su agente, los pods del agente se reinician con OOMKilled durante la primera conexión, o una lista falla con … exceeds N MiB, a quarter of this agent's memory limit (M MiB): raise the agent's resources.limits.memory.

Causa. El agente retransmite las respuestas del API server y guarda cada una entera. En un clúster con miles de ReplicaSets, una lista ocupa decenas de MB. El límite por defecto del agente era 128Mi antes de la 1.4.10; desde la 1.4.10 es 256Mi, y un cuerpo que supera una cuarta parte del límite se rechaza con el error de arriba en lugar de tumbar el pod.

Solución. Actualiza el agente a la 1.4.10, o sube su límite de memoria en su release:

helm upgrade kubebolt-agent \
  oci://ghcr.io/clm-cloud-solutions/kubebolt/helm/kubebolt-agent \
  -n kubebolt-system --reset-then-reuse-values --set resources.limits.memory=512Mi

Los insights OOMKilled y Memory Near Limit sobre un pod del agente dan este comando ya completo: el doble del límite actual, como mínimo 256Mi, fijado a la versión del chart que ejecuta el agente (para el pod promread, su propio agent.promRead.deployment.resources.limits.memory). Más detalles en El agente.

Contraseña de admin perdida

Síntoma. No puedes iniciar sesión en un KubeBolt autoalojado y nadie tiene la contraseña generada en el primer arranque. (En KubeBolt Cloud, usa Forgot password? en la página de inicio de sesión.)

Causa. La contraseña se imprime en el log de la API una sola vez, en el arranque que crea el usuario admin. Un reinicio posterior no la vuelve a imprimir.

Solución. Prueba primero con el Secret: en una instalación dentro del clúster, la contraseña generada en el primer arranque también se guarda en kubebolt-admin-password, en el namespace de la release (no refleja los cambios de contraseña posteriores, y no se crea cuando defines tú la contraseña):

kubectl -n kubebolt get secret kubebolt-admin-password \
  -o jsonpath='{.data.password}' | base64 -d ; echo

Si la contraseña se cambió después, restablécela. La vía de helm upgrade es la sencilla: el pod nuevo restablece la contraseña al arrancar y luego se inicia con normalidad:

helm upgrade kubebolt \
  oci://ghcr.io/clm-cloud-solutions/kubebolt/helm/kubebolt \
  -n kubebolt --reset-then-reuse-values --set auth.resetAdminPassword='NEW-PASSWORD'

Inicia sesión con ella, cámbiala desde el menú de la cuenta y después borra el valor:

helm upgrade kubebolt \
  oci://ghcr.io/clm-cloud-solutions/kubebolt/helm/kubebolt \
  -n kubebolt --reset-then-reuse-values --set auth.resetAdminPassword=

Ejecutar --reset-admin-password con kubectl exec dentro del pod en marcha no funciona: la API en ejecución tiene el bloqueo de la base de datos embebida, así que el restablecimiento no puede abrirla. Sin Helm, escala deployment/kubebolt-api a 0 y ejecuta el restablecimiento como un Job puntual sobre el mismo PVC (kubebolt-api --reset-admin-password=NEW-PASSWORD con KUBEBOLT_DATA_DIR=/data); el Job exacto está en el README del chart. En el binario único o en el contenedor único, detén el proceso y ejecuta kubebolt --reset-admin-password=NEW-PASSWORD sobre el mismo directorio de datos. La longitud mínima es de 8 caracteres.

Borra auth.resetAdminPassword en el siguiente helm upgrade, como arriba. Mientras esté definido, cada pod nuevo restablece la contraseña al arrancar y el valor queda guardado en los values de tu release.

En una instalación nueva, define la contraseña en lugar de ir a buscarla: --set auth.adminPassword=... (consulta Autenticación). La línea de log del primer arranque solo aparece en el arranque que creó el usuario admin:

kubectl -n kubebolt logs deployment/kubebolt-api | grep "Generated admin password"

La terminal no se abre en un clúster conectado por agente

Síntoma. La terminal de un pod muestra un error en lugar de una shell, y el explorador de archivos del pod y el port-forward también fallan. Desde la 2.6.7 la terminal dice por qué: el modo del agente no permite exec. Antes mostraba agent-proxy SPDY: expected 101 Switching Protocols, got 403.

Causa. El agente corre en modo reader, el valor por defecto del chart. Lee, y el API server le niega pods/exec. En un clúster conectado por kubeconfig, son las credenciales de ese contexto las que no pueden hacer exec.

Solución. Sube el agente al nivel operator, que añade create sobre pods/exec, pods/portforward y pods/eviction (los niveles de RBAC del agente):

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

Desde la 2.6.7, una terminal rechazada no queda registrada como sesión abierta: el registro de auditoría guarda un solo registro de apertura con result: error y el motivo del clúster.

No aparece el panel de Kobi

El botón Kobi (abajo a la derecha) y ⌘J solo aparecen cuando Kobi Copilot está configurado: una clave de API guardada en Administration → AI (Kobi), o definida con KUBEBOLT_AI_API_KEY al arrancar. La API indica en el log cuál es el caso al iniciarse:

kubectl -n kubebolt logs deployment/kubebolt-api | grep -i "AI copilot"

AI copilot enabled o AI copilot disabled (KUBEBOLT_AI_API_KEY not set); una clave guardada después desde la interfaz no cambia esa línea. Consulta Activar Kobi. En KubeBolt Cloud no hay ninguna clave que configurar: Kobi necesita un correo confirmado, y se pausa cuando se agotan los créditos de IA del mes (Créditos de IA). Si el panel se abre y Kobi responde pero no puede leer el clúster, el problema es el conector, no el copiloto: lee la entrada del 503 más arriba.

Si sigues sin solución

Abre un issue con la versión del backend, la versión del agente y la línea de log que viste, en github.com/clm-cloud-solutions/kubebolt, o cuéntanoslo en kubebolt.io/feedback.