KubeBolt docs
ENES GitHub

Configuration

Multi-Cluster

Kubeconfig contexts, agent-connected clusters, and metrics-only clusters in one persistent registry.

On this page
  1. Connection types
  2. Renaming
  3. Switching
  4. Out-of-date agents
  5. API

Connection types

The cluster registry mixes three kinds of clusters:

The registry is persistent: uploaded kubeconfigs and agent-connected clusters survive restarts, and an agent-connected cluster stays listed, out of contact, while its agent is away, until an admin deletes it. In the switcher, metrics-only clusters carry a Monitored-only badge.

Renaming

Any cluster can be renamed from the UI (admin only). Display names are stored in the registry. On KubeBolt Cloud the agent’s advertised name never overwrites a manual rename. In the open-source edition it does: an agent-connected cluster takes back <cluster.name> (via agent) when its agent reconnects or KubeBolt restarts, so name those clusters with the agent chart’s cluster.name.

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, then its informer caches load. Switching to the cluster already selected changes nothing, and its port-forwards stay open.

While a cluster loads (its first connect, after KubeBolt restarts, or after the connection was lost), the page says how far it is instead of showing a spinner: the steps (Agents connected, Access checked, Loading the cluster, First health check), a bar that follows the data still to arrive, what has arrived so far and, for an agent-connected cluster, its CPU and memory. The views open together once the cluster is ready. During a switch the menu does not show the previous cluster’s counts, and the state pill reads Connecting. The page reads GET /clusters/progress, which never starts or waits for a connect.

A connect that fails is logged (cluster runtime failed to connect, with the reason) and is not restarted by every request: requests wait 30 seconds, then 1, 2 and 4 minutes, at most 5, and their 503 says when the next attempt is. An agent reconnecting and an explicit switch to the cluster try at once. A connect fails when nothing arrives from the cluster for longer than its timeout; one that keeps receiving pages carries on, up to 10 minutes (see Troubleshooting).

How long a cluster keeps evaluating, and so notifying, depends on its kind:

ClusterEvaluated
Agent-connected (reader, operator)From the moment its agent connects, opened or not, while the agent stays connected
The cluster KubeBolt runs inAlways
Kubeconfig contextWhile open, then parked for 30 minutes after you switch away, up to eight parked at a time. Switching back after that pays the cold connect again
Metrics-onlyNo insights: there are no resource views to evaluate

So notifications cover more than the cluster on screen. The Fleet page (/fleet) shows every cluster at once.

Out-of-date agents

Since 2.7.0 KubeBolt says when a cluster’s agent is out of date, why, and the command that upgrades it. It never upgrades the agent itself: the agent is your Helm release, often under GitOps, and upgrading it from KubeBolt would take write access to its DaemonSet.

A cluster is judged by its oldest live agent:

LevelWhenShown
CurrentIt runs the newest releaseNothing
Update availableA newer release exists and nothing in this one needs fixing (agent 1.4.9 today)A neutral chip on the cluster’s card in Clusters
Update recommendedA newer release fixes something this one gets wrong: below 1.4.8 each pod’s network is stored twice (up to three times the series); below 1.4.9, with Hubble flows on, flow keys are never forgottenAn amber chip in Clusters, a tag on the cluster’s Fleet card, and a row in Home’s Needs your attention

The chip opens the reasons and the command to copy, with what to check before running it:

helm upgrade kubebolt-agent oci://ghcr.io/clm-cloud-solutions/kubebolt/helm/kubebolt-agent \
  --namespace kubebolt-system --version 1.4.10 --reset-then-reuse-values

Kobi answers whether a cluster’s agent is out of date and gives the same command; it never runs it. Agents before 1.4.4 all report 1.0.0, so they show as before 1.4.4, never as 1.0.0; Applications shows the chart actually installed. On KubeBolt Cloud, the organization’s admins also get an email when an upgrade is recommended.

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
GET    /api/v1/clusters/progress             → how far the cluster's connect has gone
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)

POST /api/v1/clusters also takes the raw kubeconfig with Content-Type: application/yaml, up to 1 MB. An empty displayName clears the rename.