tunnel

Documentation

Overview

Package tunnel implements reverse-dial tunneling between agent and hub.

Index

• func SplitBaseAndCluster(hubURL string) (base, cluster string)
• func StartProxyTunnel(ctx context.Context, hubURL string, getToken func() string, edgeName string, ...)

Functions

func SplitBaseAndCluster

func SplitBaseAndCluster(hubURL string) (base, cluster string)

SplitBaseAndCluster splits a hub URL into the base URL (scheme+host only) and the kcp cluster name embedded in the path.

For "https://faros.localhost:9443/clusters/abc123" it returns:

base    = "https://faros.localhost:9443"
cluster = "abc123"

For "https://faros.localhost:9443" (no /clusters/ path segment) it returns:

base    = "https://faros.localhost:9443"
cluster = "default"

The base URL is always used when dialling the hub so that /services/agent-proxy/ is routed by the hub's own mux before reaching the kcp reverse-proxy.

Deprecated: use apiurl.SplitBaseAndCluster directly.

func StartProxyTunnel

func StartProxyTunnel(ctx context.Context, hubURL string, getToken func() string, edgeName string, resourceType string, downstream *rest.Config, tlsConfig *tls.Config, stateChannel chan bool, sshPort int, cluster string, onAgentToken func(string), extraHeaders http.Header)

StartProxyTunnel establishes a reverse tunnel to the hub server. It runs an exponential backoff retry loop to maintain the connection. tlsConfig controls TLS verification for the WebSocket connection to the hub. Pass nil to use a default (secure) TLS config; use InsecureSkipVerify only in development environments.

resourceType must be either "kubernetes" (Kubernetes cluster agent) or "server" (bare-metal / systemd host agent). It selects which resource the agent dials on the single `edges` provider (kubernetesclusters vs linuxservers) via apiurl.ProviderAgentProxyURL.

cluster is the kcp logical cluster path (e.g., "root:faros:user-default"). If empty, it's extracted from the token (for SA tokens) or defaults to "default".

onAgentToken, if non-nil, is called on the first successful connection when the hub returns an X-Faros-Agent-Token header (token-exchange flow). The callback receives the durable token string. Callers can use this to persist the token locally so the agent can reconnect without the bootstrap join token.

getToken is invoked on every connect/reconnect attempt to obtain the current bearer token. Callers should return the SA token from the saved kubeconfig after token-exchange has succeeded, otherwise the join token is rejected on reconnect once the hub has cleared edge.Status.JoinToken.