KubeBolt docs
ENES GitHub

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.

En esta página
  1. Conexión
  2. Forma de los mensajes
  3. Tipos de eventos
  4. Entrega
  5. 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>

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

TipodataCuá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:newEl insight, como en GET /api/v1/insightsSe disparó un insight nuevo
insight:resolvedEl insightSe 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.changednullCambió 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

Los frames son JSON en las dos direcciones:

DirecciónMensaje
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.