Referencia de la API
Eventos WebSocket
Notificaciones de cambios en tiempo real mediante /api/v1/ws (cómo conectarse, qué lleva cada mensaje y qué deja fuera a propósito) y el socket de la terminal de pods.
GET /api/v1/ws hace el upgrade a un WebSocket que avisa a la interfaz de que
algo cambió para que vuelva a pedir los datos. Es un canal de
notificaciones, no de datos: los mensajes nombran lo que cambió y la
API REST sirve los datos.
Conexión
Un navegador no puede poner una cabecera Authorization en el upgrade de un
WebSocket, así que, con la autenticación activada, el
token de acceso de sesión va en la query string:
wss://kubebolt.example.com/api/v1/ws?token=<access-token>
- Aquí solo se acepta un token de acceso de sesión (de
POST /api/v1/auth/logino de/auth/refresh). Los tokens de API, no. - Un token ausente o inválido recibe
401 authentication required(texto plano) antes del upgrade. Con la autenticación desactivada, no hace falta token. - El token se comprueba una sola vez, en el upgrade. Un socket abierto sigue abierto después de que el token caduque; reconéctate con uno nuevo.
- Cualquier rol puede conectarse.
- El servidor envía un ping cada 54 segundos y corta la conexión que no haya respondido en 60. Los frames que envía el cliente se leen y se ignoran (hasta 4 KB cada uno).
En KubeBolt Cloud, conéctate a
wss://api.kubebolt.io/api/v1/ws y añade cluster=<context>, donde el
context es el de GET /api/v1/clusters. El socket recibe entonces los
eventos de recursos e insights de ese clúster y nada de ninguna otra
organización. Sin cluster, o si nombras un clúster que no pertenece a tus
equipos, el socket sigue abierto pero solo recibe los eventos de toda la
instalación (cluster:connected, cluster.switched, clusters.changed). Para
seguir otro clúster, reconéctate con su contexto.
Forma de los mensajes
Cada mensaje es un sobre JSON:
{ "type": "resource:updated", "data": { … }, "cluster": "prod-eu-west", "tenant": "…" }
cluster (el contexto que produjo el evento) y tenant aparecen en los
eventos de recursos e insights, y no en los de toda la instalación.
En los eventos de recursos, data es una notificación, no el objeto:
{
"type": "resource:updated",
"data": {
"kind": "Deployment",
"metadata": { "namespace": "shop", "name": "checkout", "uid": "…" }
},
"cluster": "prod-eu-west"
}
Para ver qué cambió, pídelo a la API REST (por ejemplo
GET /api/v1/resources/deployments/shop/checkout), que aplica el mismo
enmascaramiento y las mismas comprobaciones de rol que el resto del producto.
El socket nunca lleva el cuerpo de los objetos. Antes enviaba el objeto
completo del informer, lo que significaba que cada cambio en un Secret
llegaba a todos los navegadores conectados; desde la 2.0.3 solo envía
{kind, namespace, name, uid}.
No hay suscripción por kind: un cliente recibe todas las notificaciones de los clústeres que está viendo y decide qué volver a pedir.
Tipos de eventos
| Tipo | data | Cuándo |
|---|---|---|
resource:updated | {kind, metadata: {namespace, name, uid}} | Se agregó o cambió un objeto observado, Kubernetes Events incluidos |
resource:deleted | {kind, metadata: {namespace, name, uid}} | Se eliminó un objeto observado |
insight:new | El insight, como en GET /api/v1/insights | Se disparó un insight nuevo |
insight:resolved | El insight | Se resolvió un insight |
cluster:connected | {context, clusterId} o {context} | Se recuperó un clúster conectado por agente que había fallado, o KubeBolt seleccionó un clúster por su cuenta: la interfaz refresca el estado del clúster de inmediato |
cluster.switched | {context} | Cambió el clúster activo |
clusters.changed | null | Cambió el registro de clústeres (alta, baja, cambio de nombre) |
Solo el clúster que estás viendo emite eventos de recursos e insights. Los
clústeres aparcados en segundo plano mantienen en marcha sus informers y su
motor de insights, pero no emiten nada por el socket. En la edición open
source, todos los sockets reciben los eventos del clúster activo; usa el campo
cluster si observas más de uno.
Entrega
La entrega no está garantizada (best-effort). El hub encola hasta 4096 mensajes y descarta los nuevos cuando esa cola está llena o no hay ningún cliente conectado; cada cliente tiene su propio búfer de 256, y un cliente que no da abasto se desconecta. La interfaz se reconecta con backoff (1 segundo, duplicándose hasta 30) y su refresco periódico cubre lo que se haya perdido: haz lo mismo en tu propio cliente y trata la API REST como la fuente de verdad.
Terminal de pods
La pestaña Terminal usa un segundo socket, montado en la raíz en lugar de
bajo /api/v1:
wss://kubebolt.example.com/ws/exec/<namespace>/<pod>?token=<access-token>&container=<name>&shell=/bin/sh
- Necesita el rol Editor:
401sin un token de acceso de sesión válido y403por debajo de Editor, los dos antes del upgrade. containertoma por defecto el primer contenedor del pod.shelltoma por defecto/bin/bashsi el contenedor lo tiene y, si no,/bin/sh.- No acepta cabecera de clúster y se abre sobre el clúster seleccionado en ese momento en KubeBolt.
- Las credenciales propias de KubeBolt necesitan
createsobrepods/exec; consulta RBAC.
Los frames son JSON en las dos direcciones:
| Dirección | Mensaje |
|---|---|
| Cliente → servidor | {"type": "stdin", "data": "ls -la\n"} |
| Cliente → servidor | {"type": "resize", "cols": 120, "rows": 40} |
| Servidor → cliente | {"type": "stdout", "data": "…"} y {"type": "stderr", "data": "…"} |
| Servidor → cliente | {"type": "exit", "code": 0} cuando termina la shell |
| Servidor → cliente | {"type": "error", "message": "…"}, por ejemplo cuando el RBAC rechaza pods/exec |
Abrir y cerrar una terminal queda registrado en el registro de auditoría como una sesión de acceso, con el pod, el contenedor, la shell y el código de salida. Lo que se escribe y lo que se imprime nunca se registra.