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
- Los pods se quedan en Pending tras helm install
- El agente está conectado pero los paneles están vacíos
- Banner ámbar: “Limited access — N of M resource types restricted by RBAC”
- 503 “cluster not connected” justo después de cambiar de clúster o de reiniciar
- ”Cluster unreachable” en un clúster que sí es accesible
- ”No contact with this cluster” o “Waiting for the agent”
- El agente no llega al backend
- El agente termina en OOMKilled en un clúster grande
- Contraseña de admin perdida
- La terminal no se abre en un clúster conectado por agente
- No aparece el panel de Kobi
- 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ón | Cómo se ve | Solución |
|---|---|---|
| Agente anterior a la 1.0 | El log de la API muestra agent below minimum version — legacy schema, con agent_version y min_agent_version | Actualiza el agente (más abajo) |
| El almacén de métricas está caído | Todos los paneles de historial están vacíos en todos los clústeres; Administration → System → Health muestra que VictoriaMetrics no reporta | kubectl -n kubebolt get pods,pvc; consulta la entrada anterior si su PVC está en Pending |
| Un límite está recortando la ingesta | Un banner en Overview: Ingestion truncated by plan limits o Metric series cap engaged | En 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 minutos | Se ven los valores en vivo, pero todavía no el historial | Espera: 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.
Banner ámbar: “Limited access — N of M resource types restricted by RBAC”
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:
no cluster selected — choose a cluster to continue: elige uno en el selector de clústeres.cluster is monitored-only — enable the agent-proxy (rbac.mode=reader|operator) for resource views: el agente se ejecuta en modometrics; actualízalo con--set rbac.mode=reader.
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… | Error | Margen |
|---|---|---|
| Directo (dentro del clúster, kubeconfig) | cache sync stopped: no response from the cluster for 45s — cluster may be unreachable | Cluster connect timeout: 45 s por defecto |
| A través de un agente | connect to context … stopped: no response from the cluster for 60s — agent may be stuck | Connect 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:
- Sube el margen. Conexiones directas: Cluster connect timeout en
Administration → System → General (sin reiniciar). Clústeres conectados por
agente: Connect deadline en Administration → Agents & Ingest → Configuration
→ Agent-proxy resilience, o
KUBEBOLT_AGENT_PROXY_CONNECT_TIMEOUT(una duración de Go,60spor defecto desde la 2.6.7; nunca se aplica por debajo del timeout por petición + 5 s). Relajar el del agente debilita una protección que existe para agentes que de verdad se han quedado atascados. - Dale a la API margen para sus Events. La API los guarda en caché; el
límite de memoria por defecto del chart es 1 GiB. Si el pod de la API se
reinicia durante su primera sincronización, súbelo:
--set api.resources.limits.memory=2Gi. - Último recurso: quita
eventsde la reglaget/list/watchdel ClusterRole de KubeBolt. El clúster se levanta de inmediato; la pestaña Events y cualquier insight que lea Events se quedan vacíos, y la sonda de permisos informa, con honestidad, de un tipo de recurso menos.
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ón | Cómo se ve | Solución |
|---|---|---|
| Clúster equivocado | Nada en kubebolt-system | kubectl apuntaba a otro contexto. Cambia de contexto y vuelve a ejecutar la instalación |
| Falta el Secret del token | Pods atascados en ContainerCreating; kubectl describe pod dice secret "kubebolt-agent-token" not found | Crea 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 renderizar | backendUrl is required, o auth.mode=ingest-token requires auth.ingestToken.existingSecret | Define el valor que falta |
backendUrl lleva esquema | Errores de conexión o de dirección en el log | Es un destino de conexión gRPC (dial target), host:port, sin https:// |
| Dirección o puerto equivocados | connection refused | El 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 bloqueada | Timeouts | El agente solo abre conexiones salientes. Permite el tráfico de salida hacia el host y el puerto del backend |
| TLS no coincide | Errores 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 rechazado | code = Unauthenticated desc = agent auth: invalid credentials | Token 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 revocado | code = PermissionDenied desc = agent auth: credential rejected | La 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 another | Elimina 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.