Remote Clusters — KubeBolt Docs

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

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. That gap is the thing on the roadmap; 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 for those is on the roadmap.

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.