Connecting Clusters — KubeBolt Docs

KubeBolt supports three connection types, and you can mix them freely across your fleet. The Add cluster button on the Clusters page (Connect cluster on Fleet) offers two paths: Import kubeconfig, for a cluster whose API server this backend can reach, and Install agent, a wizard that prints the final helm command with everything you selected.

Connection types

Type	How it works	What you get
Kubeconfig	KubeBolt reads a context from the kubeconfig it was started with, or one you upload, and talks to the API server directly (in-cluster installs use their own ServiceAccount)	Live resources, actions (terminal, port-forward, scale, edit…), insights, Metrics Server data. Zero install in the cluster.
Agent	A lightweight agent runs in the cluster and connects outbound to KubeBolt over gRPC; with `rbac.mode=reader` or `operator` the backend reaches the API server through the agent’s tunnel	Live inventory, YAML, logs and insights even when the API server isn’t reachable from KubeBolt, plus historical metrics, network flows (Hubble) and optional cost data. Actions (exec, port-forward, scale, delete, edit) need `operator` mode.
Metrics-only	The agent runs with `rbac.mode=metrics`: it ships metrics but carries no API proxy	Dashboards and history for clusters you only want telemetry from; no resource inventory through this agent

Connected clusters are stored in a persistent registry — they survive restarts, and any cluster can be renamed from the UI (admin only).

Installing the agent

The agent installs from the OCI Helm registry. For a remote cluster dialing a self-hosted backend with an ingest token:

kubectl create namespace kubebolt-system
kubectl -n kubebolt-system create secret generic kubebolt-agent-token \
  --from-literal=token=<token-from-the-wizard>

helm install kubebolt-agent \
  oci://ghcr.io/clm-cloud-solutions/kubebolt/helm/kubebolt-agent \
  --namespace kubebolt-system \
  --set backendUrl=<kubebolt-agent-host>:443 --set tls.enabled=true \
  --set auth.mode=ingest-token \
  --set auth.ingestToken.existingSecret=kubebolt-agent-token \
  --set cluster.name=<cluster-name> \
  --set rbac.mode=reader

The chart never sees the token in plain text: it reads it from the Secret you create. Tokens are issued in Administration → Agents & Ingest → Agent Tokens, or by the wizard itself. backendUrl is wherever your backend’s agent gRPC port is reachable from the cluster — see Remote clusters for exposing it. For an agent in the same cluster as the backend, the in-cluster Service (kubebolt-agent-ingest.kubebolt.svc.cluster.local:9090, no TLS) is enough. On KubeBolt Cloud, the Cloud’s Add cluster wizard fills in its own ingest endpoint.

Use the wizard-generated command instead of writing this by hand — it references the Secret with your ingest token, sets the cluster name, and carries every option you toggled (RBAC mode, metrics source, Hubble, OpenCost, TLS).

Use the Helm chart. The raw manifests checked in under deploy/agent/ pin the legacy agent 0.2.2 and are kept only for reference; if you need plain manifests (air-gapped, GitOps), render them from the chart with helm template.

RBAC mode

--set rbac.mode= picks the agent ServiceAccount’s permission tier. Three values, from narrowest to widest:

Mode	Scope	What it enables
`metrics`	kubelet stats + pods list/watch + namespaces get	Metrics and Hubble flows only; no apiserver call traverses the tunnel. Implies `proxy.enabled=false`.
`reader` (default)	cluster-wide `get`/`list`/`watch` on `/`	Full read-only dashboard through the agent’s tunnel; write verbs return 403. Implies `proxy.enabled=true`.
`operator`	read + write on `/`	Exec, scale, restart, delete and YAML edit through the dashboard. Requires `auth.mode` other than `disabled` and implies `proxy.enabled=true`.

Metrics sources

The wizard’s metrics-source choice maps to these chart values:

Built-in collectors (always on) — kubelet stats and node signals collected by the agent DaemonSet; add hubble.enabled=true for Cilium Hubble flows.
Scrape sidecar (scrape.enabled=true) — a bundled vmagent scrapes Prometheus targets in the cluster and ships samples to KubeBolt, with defensive cardinality caps. It ships over remote_write, not the gRPC channel, so it also needs scrape.remoteWriteUrl pointing at the backend’s receiver (http://<kubebolt-api-service>.<namespace>.svc.cluster.local:8080/api/v1/prom/write in-cluster), and the backend must accept remote_write (metrics.remoteWrite.enabled=true on the kubebolt chart, or Administration → Agents & Ingest → Configuration). Check that the wizard’s command includes scrape.remoteWriteUrl; without it vmagent crash-loops.
Read your existing Prometheus (agent.promRead.enabled=true) — instead of scraping, a separate single-replica agent Deployment queries your Prometheus’s query_range API. This is the path for managed Prometheus: Amazon Managed Prometheus, Google Managed Prometheus, and Azure Monitor, with per-provider auth (none, basicAuth, bearer, awsSigV4 via IRSA, gcpIam via Workload Identity, azureWorkloadIdentity).

scrape.enabled and agent.promRead.enabled are mutually exclusive — one agent has one canonical source of samples. The chart fails at helm template if both are on.

Advanced options surfaced by the wizard: mTLS (CA + client Secrets), ServiceAccount annotations (IRSA / Workload Identity), tolerations, GOMEMLIMIT override, and free-form extraEnv.

Cost data (optional)

To light up the Cost tab, give the agent OpenCost data using any of the three modes described in the cost documentation — including a bundled OpenCost sub-chart (opencost.enabled=true) if you don’t already run it. The bundled OpenCost needs a Prometheus to read from; the wizard asks for its URL.

Upgrading

The agent versions independently from the backend (its own 1.x line; chart 1.4.x pairs with backend 1.10 and later, including 2.x). Upgrade with helm upgrade — avoid --reuse-values so new chart defaults apply. Which agent pairs with which backend is in Compatibility.

With clusters connected, the rest of the docs describe what you can do with them: the dashboard, the insights engine, and Kobi. If a cluster refuses to connect, start at Troubleshooting.