KubeBolt docs
ENES GitHub

Getting Started

Connecting Clusters

Three ways to connect a cluster — kubeconfig, the KubeBolt agent, or metrics-only. The Add cluster wizard generates the exact helm command for you.

On this page
  1. Connection types
  2. Installing the agent
  3. Metrics sources
  4. Cost data (optional)
  5. Upgrading
  6. Next

KubeBolt supports three connection types, and you can mix them freely across your fleet. Connecting a cluster takes the Admin role. The button is Add cluster on the Clusters page and Connect cluster on Fleet and Home (where it sits in the top bar is in Home and Fleet):

Connection types

TypeHow it worksWhat you get
KubeconfigKubeBolt reads every context of the kubeconfig it was started with, or of one you upload, and talks to the API server directly. An in-cluster install uses its own ServiceAccount insteadLive resources, actions (terminal, port-forward, scale, edit…), insights, Metrics Server data. Zero install in the cluster.
AgentA 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 tunnelLive 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-onlyThe agent runs with rbac.mode=metrics: it ships metrics but carries no API proxyDashboards and history for clusters you only want telemetry from; no resource inventory through this agent

Import kubeconfig only works when KubeBolt itself runs from a kubeconfig — the single binary, Homebrew, krew, Docker or Compose — with authentication on. An in-cluster install (the Helm chart) and KubeBolt Cloud refuse an upload with cannot add clusters in in-cluster mode: connect their other clusters with the agent. Every context in the uploaded file is added; a context whose name already exists has to be renamed first. The credentials must work from where the backend runs — an exec plugin such as aws eks get-token needs that CLI inside the container.

Connected clusters are stored in a persistent registry — they survive restarts, and any cluster can be renamed or deleted from the Clusters page (admin only). A cluster whose agent stops stays listed, out of contact and showing its last known state, until you delete it.

Installing the agent

The agent installs from the OCI Helm registry. For a remote cluster dialing a self-hosted backend with an ingest token, set three variables and run the rest as is:

export KB_TOKEN='kb_...'                          # from the wizard or Agent Tokens
export KB_BACKEND='agent.kubebolt.example.com:443' # host:port, no scheme
export KB_CLUSTER='prod-eu'                        # how it shows up in KubeBolt

kubectl create namespace kubebolt-system
kubectl -n kubebolt-system create secret generic kubebolt-agent-token \
  --from-literal=token="$KB_TOKEN"

helm install kubebolt-agent \
  oci://ghcr.io/clm-cloud-solutions/kubebolt/helm/kubebolt-agent \
  --namespace kubebolt-system \
  --set backendUrl="$KB_BACKEND" --set tls.enabled=true \
  --set auth.mode=ingest-token \
  --set auth.ingestToken.existingSecret=kubebolt-agent-token \
  --set cluster.name="$KB_CLUSTER" \
  --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, and are shown once. Since 2.6.5 a token a wizard hands you to copy stops working if no agent uses it within 7 days; once an agent has used it, it keeps working. The wizard says until when, and Agent Tokens shows it. A token KubeBolt writes straight into the cluster’s Secret has no such window.

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).

Check it worked. One agent pod per node should be Running, and the log should show channel registered within a minute:

kubectl -n kubebolt-system get pods -l app.kubernetes.io/name=kubebolt-agent
kubectl -n kubebolt-system logs ds/kubebolt-agent --tail=20

The cluster then appears in the cluster switcher and in Fleet, and Administration → Agents & Ingest → Activity lists the agent. If it doesn’t, see Troubleshooting.

Where the agent dials

backendUrl is a gRPC dial target, host:port, never a URL with a scheme:

KubeBolt runs…backendUrlTLS / auth
In the same cluster (Helm release kubebolt in namespace kubebolt)kubebolt-agent-ingest.kubebolt.svc.cluster.local:9090 (<release>-agent-ingest.<namespace>)TLS off
Self-hosted, behind the chart’s Gateway API agent listeneragent.<your-domain>:443tls.enabled=true
Self-hosted, agent port exposed as a LoadBalancer or NodePortthat address and portTLS only if agentIngest.tls is on
On your laptop (binary, Homebrew, krew, Docker), agent in kind, k3d, minikube or Docker Desktophost.docker.internal:9090 (on Linux, your machine’s address on the Docker network)TLS off
KubeBolt Cloudagent.kubebolt.io:443 — the Cloud wizard fills it intls.enabled=true, auth.mode=ingest-token

For a cluster KubeBolt already reaches directly (the one it runs in, or a kubeconfig context), there is also a no-Helm path: Administration → Agents & Ingest → Integrations → KubeBolt Agent → Install applies the agent through KubeBolt’s own connection. That agent is managed from the same panel, not by helm upgrade.

Exposing the agent port

A self-hosted backend listens for agents on gRPC port 9090 of the <release>-agent-ingest Service, which is ClusterIP by default. The chart’s Ingress does not carry it. For agents in other clusters, pick one:

Then set, on the kubebolt chart:

ValueWhat it does
agentIngest.externalUrlThe public host:port agents dial. The wizard then pre-fills it and turns TLS and token auth on
agentIngest.authModedisabled (default) accepts any agent that reaches the port; permissive authenticates, logs failures and still accepts; enforced rejects agents without a valid token. Also in Administration → Agents & Ingest → Configuration (applies after a restart)

With the default agentIngest.authMode=disabled, anyone who can reach the agent port can register a cluster and push metrics. Set enforced before exposing the port beyond a network you trust.

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:

ModeScopeWhat it enables
metricskubelet stats + pods list/watch + namespaces getMetrics and Hubble flows only; no apiserver call traverses the tunnel. The cluster is listed as metrics-only, and resource views answer 503 cluster is monitored-only. 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.
operatorread + write on */*Exec, scale, restart, delete and YAML edit through the dashboard. Effectively cluster-admin for the agent, so use it only with an authenticated agent (auth.mode ingest-token or tokenreview): the wizards refuse it without a token, the chart does not check. Implies proxy.enabled=true.

Your KubeBolt role still applies on top: a Viewer can’t scale anything, whatever the agent may do.

Agent authentication

--set auth.mode= is how the agent proves who it is to the backend:

ModeWhen
disabled (chart default)The backend accepts unauthenticated agents (agentIngest.authMode disabled or permissive). Fine next to the backend on a trusted network
tokenreviewAgent in the same cluster as the backend: a projected ServiceAccount token the backend checks with the TokenReview API. Nothing to issue
ingest-tokenAny other cluster, and always on KubeBolt Cloud: a token from Agent Tokens, read from the Secret named in auth.ingestToken.existingSecret

Metrics sources

The wizard’s metrics-source choice (under Advanced) maps to these chart values:

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), node selector, tolerations, resources, image and priority class, 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. Use one source of cost per agent: since agent 1.4.10 the chart refuses agent.promRead.cost.enabled together with the OpenCost exporter.

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 the backend first, then the agent in every cluster that runs one, with that cluster’s kubectl context:

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

--reset-then-reuse-values (Helm 3.14+) keeps your values and takes the new chart’s defaults; plain --reuse-values keeps the old chart’s pinned images. Use the namespace you installed into (helm list -A | grep kubebolt-agent). An agent installed from Integrations is not a Helm release: restart it (kubectl -n kubebolt-system rollout restart daemonset/kubebolt-agent) to pull the new image. Which agent pairs with which backend is in Compatibility. Since 2.7.0 the Clusters page says when a cluster’s agent should be upgraded, with the command (Multi-Cluster).

Next

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