Connect resources to an HA Proxy pool¶

A Connector registers through the public Proxy entry and keeps tunnels to distinct Proxy identities. Use this procedure with either Authority routing topology. The public LB carries registration and tunnels; Proxy peers and Authority addresses stay private.

Before you start¶

Input	IP-only example	Check
Ready Proxy pool	Public entry `203.0.113.10`	Both Proxy backends ready; round-robin tunnel routing
Registration	`https://203.0.113.10:50064`	Join relay enabled on Proxies and advertised by every Authority
Trust	Approved cluster CA fingerprint	Obtain from the Authority operator through a trusted channel
Resource	SSH host `demo-ssh`, onward mode `local`	Assigned publication scope or explicit manual membership
Identity	Unique name `conn-1` and persistent state directory	Preserve this node's identity across restarts

For DNS public TLS, use https://gate.example.com:50061 and its public trust for the DNS variant of these registration commands. A private Authority registration certificate is independent of that public certificate.

Issue a Connector permission¶

On an admitted Authority:

(umask 077; gdsgate authority tokens create --role connector > connector.token)

New installations use automatic publication: an admitted Connector publishes ordinary configured backends inside its Registry namespace. No separate resources set is needed. The active policy still decides user access. Existing manual nodes retain their mode. For a shared manual resource, use explicit Registry assignments.

Register and start¶

Transfer the permission through the protected operator channel. Choose the service or foreground installation and preserve its private state:

Linux serviceForegroundWindows service

Run in a root shell:

PUBLIC_ENTRY=203.0.113.10
CA_FINGERPRINT='<approved SHA-256 fingerprint>'
gdsgate join "$PUBLIC_ENTRY" --name conn-1 \
  --fingerprint "$CA_FINGERPRINT" --serve demo-ssh=ssh --start < connector.token
rm connector.token
gdsgate setup change --connector-config /etc/gdsgate/connector.toml \
  --set connector:connector.proxy_connection_count=2
systemctl restart gdsgate-connector
gdsgate --config /etc/gdsgate/connector.toml doctor --explain

Run as the account that owns this Connector:

PUBLIC_ENTRY=203.0.113.10
CA_FINGERPRINT='<approved SHA-256 fingerprint>'
gdsgate join "$PUBLIC_ENTRY" --name conn-workstation \
  --fingerprint "$CA_FINGERPRINT" --serve demo-ssh=ssh \
  --state-dir ~/.gdsgate/ha-connector-state \
  --output ~/.gdsgate/ha-connector.toml < connector.token
gdsgate setup change --connector-config ~/.gdsgate/ha-connector.toml \
  --set connector:connector.proxy_connection_count=2
gdsgate --config ~/.gdsgate/ha-connector.toml connector

Run in an elevated PowerShell prompt:

$PublicEntry = "203.0.113.10"
$Fingerprint = "<approved SHA-256 fingerprint>"
Get-Content -Raw connector.token | gdsgate join $PublicEntry --name conn-1 `
  --fingerprint $Fingerprint --serve demo-ssh=ssh --start
Remove-Item connector.token
gdsgate setup change --connector-config "$env:ProgramData\gdsgate\connector.toml" `
  --set connector:connector.proxy_connection_count=2
Restart-Service gdsgate-connector
gdsgate --config "$env:ProgramData\gdsgate\connector.toml" doctor --explain

The verified bundle supplies registration, renewal and tunnel endpoints and transport trust. --fingerprint allows unattended private-CA discovery; otherwise an unknown CA requires terminal confirmation. --route, registration port and CA file are unnecessary for the advertised route. Public DNS trust and internal transport trust are verified separately.

The connection-count default remains 1. This HA example explicitly selects 2 distinct verified Proxies to keep tunnels on separate nodes. A Connector with one tunnel can still be reached through authenticated Proxy peering. HA does not copy or fail over the backend itself.

An automatic SSH resource is normally listed as conn-1/demo-ssh. Its short demo-ssh alias works only while unambiguous. A different node declaring that local name gets a different qualified ID and UID. See resource identities.

Verify admission and access¶

On the Connector host, using its actual configuration:

gdsgate --config /etc/gdsgate/connector.toml doctor --explain

For a foreground installation, use ~/.gdsgate/ha-connector.toml. The tunnel check must report 2 verified distinct Proxy nodes, 2 desired; the catalogue check must admit conn-1/demo-ssh with onward_auth=local. Read the named checks: doctor can also infer other roles from this configuration, so unrelated local Authority checks do not describe the remote Authority group.

On Authority, verify the serving route:

gdsgate --config /etc/gdsgate/authority.toml authority resources list
gdsgate --config /etc/gdsgate/authority.toml authority serving list

Then perform an allowed native SSH operation and a denied one from a logged-in client. A catalogue row or serving=yes alone does not prove native access. Complete HA acceptance, including a new connection after one Proxy stops and delivery of the resulting recording.

Startup and failures¶

Message / symptom	Meaning	Action
INFO `acquiring activation receipt before serving resource`	This run has not obtained its capability receipt yet	Wait for renewal through the bootstrap relay
INFO `activation receipt acquired; re-registering tunnel`	Planned registration with the new receipt	Confirm both verified tunnels and admitted resources afterwards
`not_in_catalog`	No matching catalogue row	Declare the resource on Authority
`mode_not_confirmed`	Catalogue has no required SSH mode	Set the intended `onward_auth` or `ssh_profile` on Authority
Persistent `gate_not_offered`	Capability receipt has not made the resource admissible	Inspect renewal, activation and Authority errors; adding the existing row again does not obtain a receipt
`owned_by_another_node`	Another enrolled node owns the serving lease	Use that node or follow the node replacement procedure
`namespace_not_admitted`	The registered identity cannot serve this resource	Check the assigned namespace, ownership, suppression and catalog lease
`Proxy identity could not be confirmed`	Authority could not attest the actual TLS peer	Inspect relay, node registry and Authority logs; the tunnel remains unverified
Only one verified Proxy	LB affinity, unreachable backend, or duplicate Proxy identity	Check round-robin tunnel routing, separate identities and both readiness endpoints
`UnknownIssuer` during join	Registration CA is not trusted	Use the approved CA pin or `--enroll-ca`; inspect the endpoint and TLS name

Receipt acquisition happens on each process start, even when the persisted transport identity is reused. An identity lookup interrupted by a replaced relay can repeat its read within the call ceiling. Credential issuance and state-changing RPCs are not automatically replayed by that mechanism.

Restarting this process uses the same transport identity. A fresh token and --force are for deliberate node replacement, not recovery of a tunnel.