The Agent — KubeBolt Docs

KubeBolt works with just a kubeconfig. The agent is the optional next step: a lightweight component you install in a cluster to unlock historical metrics, Hubble network flows, and cost data. It connects outbound only over gRPC — the cluster’s API server is never exposed, which is what makes private, firewalled and egress-restricted clusters workable.

The chart runs up to two workloads, configured in the Add Cluster wizard:

DaemonSet (always) — collects kubelet stats per node (plus Hubble flows when present) and ships them to KubeBolt’s embedded metrics store. With rbac.mode=reader or operator it also carries the tunnel that lets KubeBolt reach the cluster’s API.
promread Deployment (when agent.promRead.enabled=true) — a single replica, added next to the DaemonSet, that reads the metric families the DaemonSet doesn’t produce (kube-state-metrics, node load and pressure, disk and network errors) from a Prometheus you already run, including the managed offerings (AMP, GMP, Azure Monitor) with per-provider auth (basic, bearer, AWS SigV4, GCP IAM, Azure Workload Identity).

The chart

The agent ships as its own OCI chart, generated with the right values by the wizard:

helm install kubebolt-agent \
  oci://ghcr.io/clm-cloud-solutions/kubebolt/helm/kubebolt-agent \
  --namespace kubebolt-system --create-namespace \
  --set backendUrl=kubebolt-agent-ingest.kubebolt.svc.cluster.local:9090

Key values (see the chart’s values.yaml for the full, commented reference):

Value	Purpose
`backendUrl`	Where the agent dials home — a gRPC dial target as `<host:port>`, no scheme (required). In-cluster this is the chart’s `-agent-ingest` Service on 9090, not the web Service
`cluster.name` / `cluster.id`	How the cluster registers and displays in KubeBolt
`hubble.*`	Enable network-flow collection from an existing Hubble relay
`collectors.*`	Tune what gets collected (exporters, interface drops, …)
`opencost.*`	Cost sourcing — bundled OpenCost sub-chart, or `exporterUrl` for one you already run (details)
`agent.promRead.*`	`promread` mode — endpoint `url`, per-provider `auth`, optional `cost.enabled`
`scrape.*`	Optional scrape sidecar with relabeling and discovery controls
`auth.mode`	Backend authentication: `disabled`, `tokenreview` (same-cluster), or `ingest-token` (issued in the admin UI; required for cross-cluster/SaaS)
`rbac.mode`	How much the agent’s ServiceAccount may do: `metrics`, `reader` (default), or `operator` (details)
`tls.*`	Transport TLS and optional mTLS (CA bundle, client cert, SNI override)
`gomemlimit`	Explicit Go memory target for tight nodes

Versioning

The agent follows its own release cadence (currently the 1.4.x line) on a stable v1.0 metric/label schema. The schema is the only contract between the two sides, so any 1.x agent ≥ 1.0 pairs with any KubeBolt backend ≥ 1.10 — upgrade either side independently within those bounds. Agent 0.2.x emits the pre-canonical schema and renders empty dashboards against a modern backend; the backend logs a WARN on registration when one connects.

promRead is the one mode with a narrower window: it shipped in agent 1.1.0 alongside backend 1.13.0. Its samples still reach the metrics store on backends 1.10–1.12, but the Prometheus (read) integration card doesn’t render there. That is a floor for one mode, not a floor for the agent — it was being quoted as the general rule. Full matrix in Compatibility.

The agent’s own changelog lists every version on its line, without the backend releases in between: packages/agent/CHANGELOG.md.

Upgrade with your values explicit (or a values file) rather than --reuse-values, so new chart defaults aren’t pinned to old values.

Security posture: outbound-only connection, no inbound ports, runs as non-root, and authenticates with a scoped ingest token in cross-cluster setups. Metrics flow through the backend — the agent never writes to the metrics store directly.