Multi-Cluster — KubeBolt Docs

Connection types

The cluster registry mixes three kinds of clusters:

Kubeconfig contexts — auto-discovered from your kubeconfig at startup, or added later by uploading a kubeconfig (admin). The initial connection targets the current-context.
Agent-connected clusters — added through the Add Cluster wizard; the agent dials outbound to KubeBolt, so no inbound network path or shared kubeconfig is needed. Remote exec, port-forward, and the file browser work over the same channel (see Remote Clusters).
Metrics-only clusters — the agent runs with rbac.mode=metrics: it ships telemetry, but no apiserver call crosses its tunnel. Ideal for clusters you only want on dashboards; resource views need a reader or operator agent.

The registry is persistent: registered clusters survive restarts, and the UI badges each cluster with its connection type.

Renaming

Any cluster can be renamed from the UI (admin only). Display names are stored in the registry — the agent’s advertised name never overwrites a manual rename.

Switching

When switching clusters, the manager parks the current connector instead of tearing it down: its informers, metrics collector and insights engine keep running in the background, so switching back to a cluster you already opened is instant. A cluster you haven’t opened yet is connected on first use — the permission probe runs for it, and the frontend shows a “Connecting to cluster” overlay while it does.

Because parked clusters keep evaluating, insights and notifications cover every connected cluster, not only the one on screen. The Fleet page (/fleet) shows all of them at once.

API

Any API call can target a cluster other than the active one with the X-KubeBolt-Cluster: <context-name> header.

GET    /api/v1/clusters                      → list registered clusters
POST   /api/v1/clusters/switch               → { "context": "production-eks" }
POST   /api/v1/clusters                      → { "kubeconfig": "<yaml>" }         (admin)
PUT    /api/v1/clusters/{context}/rename     → { "displayName": "prod-us-east" }   (admin)
DELETE /api/v1/clusters/{context}            → remove an uploaded context          (admin)
DELETE /api/v1/clusters/by-id/{clusterId}    → remove an agent-connected cluster   (admin)