KubeBolt docs
ENES GitHub

API Reference

WebSocket Events

Real-time change notifications via /api/v1/ws — connecting, what each message carries and what it deliberately doesn't — and the pod-terminal socket.

On this page
  1. Connecting
  2. Message shape
  3. Event types
  4. Delivery
  5. Pod terminal

GET /api/v1/ws upgrades to a WebSocket that tells the UI something changed so it can refetch. It is a notification feed, not a data feed: the payloads name what changed, and the REST API serves the data.

Connecting

A browser cannot set an Authorization header on a WebSocket upgrade, so when authentication is enabled the session access token goes in the query string:

wss://kubebolt.example.com/api/v1/ws?token=<access-token>

On KubeBolt Cloud, connect to wss://api.kubebolt.io/api/v1/ws and add cluster=<context> — the context from GET /api/v1/clusters. The socket then receives that cluster’s resource and insight events and nothing from any other organization. Without cluster, or naming a cluster your teams don’t own, the socket stays open but only receives the install-wide events (cluster:connected, cluster.switched, clusters.changed). To follow another cluster, reconnect with its context.

Message shape

Every message is a JSON envelope:

{ "type": "resource:updated", "data": { … }, "cluster": "prod-eu-west", "tenant": "…" }

cluster (the context that produced the event) and tenant are present on resource and insight events and absent on install-wide ones.

For resource events, data is a notification, not the object:

{
  "type": "resource:updated",
  "data": {
    "kind": "Deployment",
    "metadata": { "namespace": "shop", "name": "checkout", "uid": "…" }
  },
  "cluster": "prod-eu-west"
}

To see what changed, fetch it through the REST API (for example GET /api/v1/resources/deployments/shop/checkout), which applies the same redaction and role checks as the rest of the product.

The socket never carries object bodies. It used to send the full informer object, which meant every Secret change reached every connected browser; since 2.0.3 it sends only {kind, namespace, name, uid}.

There is no per-kind subscription: a client receives every notification for the clusters it is viewing and decides what to refetch.

Event types

TypedataWhen
resource:updated{kind, metadata: {namespace, name, uid}}A watched object was added or changed — Kubernetes Events included
resource:deleted{kind, metadata: {namespace, name, uid}}A watched object was removed
insight:newThe insight, as in GET /api/v1/insightsA new insight fired
insight:resolvedThe insightAn insight resolved
cluster:connected{context, clusterId} or {context}A previously-failed agent-connected cluster recovered, or KubeBolt selected a cluster on its own — the UI refreshes cluster state immediately
cluster.switched{context}The active cluster changed
clusters.changednullThe cluster registry changed (added, removed, renamed)

Only the cluster you are viewing emits resource and insight events. Clusters parked in the background keep their informers and insights engine running, but stay quiet on the socket. In the open-source edition every socket receives the events of the active cluster; use the cluster field if you watch more than one.

Delivery

Delivery is best-effort. The hub queues up to 4096 messages and drops new ones when that queue is full or no client is connected; each client has its own buffer of 256, and a client that can’t keep up is disconnected. The UI reconnects with backoff (1 second, doubling up to 30) and its periodic refetch covers anything missed — do the same in your own client and treat the REST API as the source of truth.

Pod terminal

The Terminal tab uses a second socket, mounted at the root rather than under /api/v1:

wss://kubebolt.example.com/ws/exec/<namespace>/<pod>?token=<access-token>&container=<name>&shell=/bin/sh

Frames are JSON in both directions:

DirectionMessage
Client → server{"type": "stdin", "data": "ls -la\n"}
Client → server{"type": "resize", "cols": 120, "rows": 40}
Server → client{"type": "stdout", "data": "…"} and {"type": "stderr", "data": "…"}
Server → client{"type": "exit", "code": 0} when the shell ends
Server → client{"type": "error", "message": "…"}, for example when RBAC refuses pods/exec

Opening and closing a terminal is recorded in the audit trail as an access session, with the pod, container, shell and exit code. What is typed and printed is never recorded.