Documentation
¶
Overview ¶
Package tunnel implements reverse-dial tunneling between agent and hub.
Index ¶
Constants ¶
const DefaultSvcPolicy = SvcPolicyWarn
DefaultSvcPolicy is the policy used when --svc-policy is not given. This release defaults to warn so existing Services that point off the loopback keep working while the agent logs what enforce would block; the next release flips the default to enforce.
Variables ¶
This section is empty.
Functions ¶
func ParseSvcAllowedCIDRs ¶
ParseSvcAllowedCIDRs parses --svc-allow-cidr values (each a CIDR such as 192.168.1.0/24 or 10.0.0.5/32; a bare IP is treated as a /32 or /128).
func SplitBaseAndCluster
deprecated
SplitBaseAndCluster splits a hub URL into the base URL (scheme+host only) and the kcp cluster name embedded in the path.
For "https://railgrid.localhost:9443/clusters/abc123" it returns:
base = "https://railgrid.localhost:9443" cluster = "abc123"
For "https://railgrid.localhost:9443" (no /clusters/ path segment) it returns:
base = "https://railgrid.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, svc SvcProxyOptions, 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 is "kubernetes" (Kubernetes cluster agent), "server" (Linux bare-metal / systemd host agent), or "macos" (service-only macOS host agent). It selects which resource the agent dials on the single `edges` provider via apiurl.ProviderAgentProxyURL.
cluster is the kcp logical cluster path (e.g., "root:railgrid: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-Railgrid-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.
svc is the /svc proxy host policy (--svc-allow-cidr / --svc-policy); see SvcProxyOptions and newSvcProxyHandler.
Types ¶
type SvcPolicy ¶
type SvcPolicy string
SvcPolicy selects what the agent does when a /svc target fails the host checks (see SvcProxyOptions).
const ( // SvcPolicyEnforce refuses a disallowed target with 403 and never dials it. SvcPolicyEnforce SvcPolicy = "enforce" // SvcPolicyWarn dials a disallowed target anyway but logs the denial and // stamps X-Railgrid-Svc-Policy: warn on the response, so operators can find // the Services that need --svc-allow-cidr before flipping to enforce. SvcPolicyWarn SvcPolicy = "warn" // SvcPolicyAllowAny disables the allow list entirely (loudly logged at // startup). Link-local, unspecified, multicast and the cloud metadata // endpoints in svcHardBlockedPrefixes stay blocked even here — those are // never overridable. SvcPolicyAllowAny SvcPolicy = "allow-any" )
func ParseSvcPolicy ¶
ParseSvcPolicy validates a --svc-policy value. Empty selects DefaultSvcPolicy.
type SvcProxyOptions ¶
type SvcProxyOptions struct {
// AllowedCIDRs are the literal-IP ranges (and resolved-hostname ranges)
// the agent may dial besides loopback and, in kubernetes mode, cluster DNS.
AllowedCIDRs []netip.Prefix
// Policy decides what happens when a target is outside that set.
Policy SvcPolicy
}
SvcProxyOptions is the operator-configured part of the /svc proxy policy, set from --svc-allow-cidr / --svc-policy (or RAILGRID_AGENT_SVC_ALLOW_CIDR / RAILGRID_AGENT_SVC_POLICY) and threaded from agent.Options down to the tunnel's remote server.
Source Files