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.
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):
- While no cluster is connected, it opens the first-cluster wizard: name the cluster (self-hosted, also confirm the address the agent dials), paste one install block, and it waits until the agent reports. Its Advanced setup leads to every option below, reusing the wizard’s token and name instead of issuing a second token, and Back to the simple setup returns to it; the Cloud walkthrough is Getting started on Cloud.
- Once there is a cluster, it opens a menu with two paths: Install agent
(recommended), a wizard that prints the final
helmcommand with everything you selected, and Import kubeconfig, for a cluster whose API server this backend can reach.
Connection types
| Type | How it works | What you get |
|---|---|---|
| Kubeconfig | KubeBolt 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 instead | 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 |
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… | backendUrl | TLS / 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 listener | agent.<your-domain>:443 | tls.enabled=true |
| Self-hosted, agent port exposed as a LoadBalancer or NodePort | that address and port | TLS only if agentIngest.tls is on |
| On your laptop (binary, Homebrew, krew, Docker), agent in kind, k3d, minikube or Docker Desktop | host.docker.internal:9090 (on Linux, your machine’s address on the Docker network) | TLS off |
| KubeBolt Cloud | agent.kubebolt.io:443 — the Cloud wizard fills it in | tls.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:
- Gateway API —
gatewayAPI.enabled=truewithgatewayAPI.agent.host=agent.example.comadds a TLS listener on 443 with aGRPCRouteto the agent port (see Installation methods). If a CDN proxies your DNS, keep that hostname DNS-only: proxies break long-lived bidirectional gRPC. - LoadBalancer or NodePort —
--set agentIngest.service.type=LoadBalancer, orNodePortwith a fixedagentIngest.service.nodePort. This is plain gRPC unless you also setagentIngest.tls.enabled=trueandagentIngest.tls.existingSecret(a Secret withtls.crtandtls.key).
Then set, on the kubebolt chart:
| Value | What it does |
|---|---|
agentIngest.externalUrl | The public host:port agents dial. The wizard then pre-fills it and turns TLS and token auth on |
agentIngest.authMode | disabled (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:
| Mode | Scope | What it enables |
|---|---|---|
metrics | kubelet stats + pods list/watch + namespaces get | Metrics 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. |
operator | read + 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:
| Mode | When |
|---|---|
disabled (chart default) | The backend accepts unauthenticated agents (agentIngest.authMode disabled or permissive). Fine next to the backend on a trusted network |
tokenreview | Agent in the same cluster as the backend: a projected ServiceAccount token the backend checks with the TokenReview API. Nothing to issue |
ingest-token | Any 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:
- None — kubelet metrics only (always on) — kubelet stats and node signals
collected by the agent DaemonSet; add
hubble.enabled=truefor Cilium Hubble flows. - Scrape annotated pods (
scrape.enabled=true) — a bundledvmagentsidecar scrapes pods annotatedprometheus.io/scrape: "true"and ships samples to KubeBolt, with defensive cardinality caps; node-exporter and kube-state-metrics discovery are opt-in (scrape.discovery.nodeExporter.enabled,scrape.discovery.kubeStateMetrics.enabled). It ships overremote_write, not the gRPC channel, so it needsscrape.remoteWriteUrlpointing at the backend’s receiver (http://kubebolt-api.kubebolt.svc.cluster.local:8080/api/v1/prom/writefor the in-cluster releasekubebolt), and the backend must acceptremote_write(metrics.remoteWrite.enabled=trueon thekubeboltchart, or Administration → Agents & Ingest → Configuration). The wizard’s command does not includescrape.remoteWriteUrl— add it yourself, or vmagent crash-loops. - Read from existing Prometheus (
agent.promRead.enabled=true) — instead of scraping, a separate single-replica agent Deployment queries your Prometheus’squery_rangeAPI. This is the path for managed Prometheus: Amazon Managed Prometheus, Google Managed Prometheus, and Azure Monitor, with per-provider auth (none,basicAuth,bearer,awsSigV4via IRSA,gcpIamvia 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), 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.