Configuration
Remote Clusters
Operate clusters KubeBolt can't reach directly — the in-cluster agent dials out, nothing dials in. Exec, port-forward, and the file browser all work over the tunnel.
Not every cluster is reachable from where KubeBolt runs — private GKE/EKS control planes, clusters behind a bastion, or networks with no inbound path. In agent-proxy mode an in-cluster agent opens an outbound connection to the KubeBolt backend and tunnels operations back over it. Nothing dials in: no exposed API server, no firewall holes, no VPN.
You rarely write this configuration by hand: in both the open-source edition and KubeBolt Cloud, the Add cluster wizard generates the agent install command for your connection mode — paste it once and the tunnel is up.
What a self-hosted backend needs
On KubeBolt Cloud this is already in place. On your own backend, the wizard covers the agent side once four things hold:
- Agents can reach the gRPC port. The chart exposes it as the
<release>-agent-ingestService on 9090. Make it reachable from the remote cluster withagentIngest.service.type(LoadBalancerorNodePort) or the Gateway API route (gatewayAPI.agent.*), and put the publichost:portinagentIngest.externalUrl(KUBEBOLT_AGENT_INGEST_URL): the wizard then uses it as the agent’sbackendUrland defaults to TLS and an ingest token. A CDN in front of that host breaks bidirectional gRPC: keep it DNS-only. - Auto-registration is on, or the remote cluster ships metrics but never appears in the switcher. The Helm chart turns it on; with the binary or Docker Compose, switch it on in Administration → Agents & Ingest → Configuration (no restart).
- Agents authenticate. Issue an ingest token in Administration → Agents
& Ingest → Agent Tokens and install the agent with
auth.mode=ingest-token, then set the backend’s agent auth mode (agentIngest.authMode,KUBEBOLT_AGENT_AUTH_MODE) toenforced; that one needs a restart.tokenreviewonly works when the agent and the backend share a cluster. - The channel is encrypted: TLS on the backend (
agentIngest.tls.*) or at the Gateway or load balancer in front of it, andtls.enabled=trueon the agent.
The variables behind each of these are in Environment variables.
What works over the tunnel
This isn’t read-only mirroring — full-stack operation works against a remote backend:
- Terminal / exec — open a shell into a container.
- Port-forward — reach a service running in the remote cluster.
- File browser — navigate and read files inside a container.
What the tunnel may do follows the agent’s rbac.mode: reader gives a full
read-only dashboard, and exec, scale, restart, delete and YAML edits need
operator (see RBAC). Your KubeBolt role
still applies on top.
Every API response crosses the tunnel through the agent, which holds each one whole. KubeBolt asks for lists in pages of 500 objects, and since agent 1.4.10 a body past a quarter of the agent’s memory limit is answered with an error instead of an OOMKill. On a cluster with thousands of objects, give the agent more memory: see The Agent.
Port-forward over HTTP
Port-forwards use client-go’s SPDY stream, and on agent-proxy clusters that SPDY
stream rides inside the agent’s gRPC AgentChannel. It is exposed through an
HTTP reverse proxy at /pf/{id}/, so the dashboard can open a forwarded service
without direct network access to the backend. A tunnel — exec, port-forward or
file browser — closes after 5 minutes without traffic
(KUBEBOLT_AGENT_TUNNEL_IDLE_TIMEOUT).
Under the hood POST /portforward does bind a real TCP listener, on the
backend host, through client-go — that is what /pf/{id}/ proxies into.
What does not exist is a raw TCP endpoint reachable from your machine: unless
you can already route to the backend’s network, a database client has nothing to
connect to. The HTTP path is what ships.
Known limitations. Apps that hard-code absolute root paths (/static,
/api) won’t render cleanly through /pf/{id}/ without a sub-path config on
the app itself — for example Grafana’s root_url. And because the exposed
surface is HTTP, a non-HTTP protocol (Postgres, MySQL, Redis) cannot be
reached through it: raw TCP forwarding to your machine is not available.
The HTTP remote path has been validated end-to-end across the public internet through a Caddy reverse proxy with TLS, with the operator agent running in a separate cluster from the backend.