Configuration
Multi-Cluster
Kubeconfig contexts, agent-connected clusters, and metrics-only clusters in one persistent registry.
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. When KubeBolt runs inside a cluster with no kubeconfig file (the Helm install), that cluster is its one context and uploads are refused: add other clusters with the agent.
- 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). They appear in the switcher when their agent first connects, which needs cluster auto-registration on: the Helm chart’s default, but off by default in the binary and Docker Compose (Administration → Agents & Ingest → Configuration, no restart).
- 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 and insights need areaderoroperatoragent.
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:
| Cluster | Evaluated |
|---|---|
Agent-connected (reader, operator) | From the moment its agent connects, opened or not, while the agent stays connected |
| The cluster KubeBolt runs in | Always |
| Kubeconfig context | While 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-only | No 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:
| Level | When | Shown |
|---|---|---|
| Current | It runs the newest release | Nothing |
| Update available | A 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 recommended | A 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 forgotten | An 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
- It runs against kubectl’s current context: check it is that cluster
(
kubectl config current-context) or add--kube-context <name>. - Installed with another release name or namespace, change
kubebolt-agentandkubebolt-system. --reset-then-reuse-valueskeeps your settings and takes the new chart’s defaults (Helm 3.14 or later). A release installed with a full copy of the chart’s values file keeps the old defaults as settings:helm get values kubebolt-agent -n kubebolt-systemshows what it keeps.- With Argo CD or Flux, set the chart version in the Application or HelmRelease instead.
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.