Enrollment configuration

Paths in the tables are relative to [enroll]. Check parsing and cross-field rules with gdsgate doctor --config <PATH> --json. See the registration lifecycle guide.

[enroll]

Used by: Proxy, Connector.

A standalone Proxy or Connector uses this section to get its transport identity for internal mutual TLS. With endpoint set and a token in the file or in GDSGATE_ENROLL_TOKEN, the node registers on first start. Later starts reuse the identity in state_dir.

For a connector, gdsgate join registers and writes this section without a token.

Key	Type	Default	Purpose
endpoint	optional string	unset, enrollment off	Authority registration URL. A tunnelled connector derives the address from endpoints.proxy_join when this is unset.
token	optional string	unset	One-time registration token. Use GDSGATE_ENROLL_TOKEN or a secret reference (${file:...}, ${env:...}, ${exec:...}) to keep it out of the file. A bare value is the token.
state_dir	optional string	unset, per-role directory under ~/.gdsgate/state	Directory for the persisted transport identity and SSH model A host key.
renew_endpoint	optional string	unset, derived from the Authority or tunnel relay	Authority mTLS endpoint for token-less renewal. It must use https://.
background_renewal	bool	true	Renew the transport certificate while running.
node_name	optional string	unset	Registry label sent on join. Not taken from the host name; must pass the charset and length check.
transport_ca	optional string	unset, platform trust store	PEM anchor for an HTTPS registration listener. Refused with an http:// endpoint. For a certificate the cluster CA issued: the cluster CA; see Registration at an IP address.
transport_sni	optional string	unset, the host in endpoint	TLS server name to verify in place of the dialed host. Use it when endpoint is a loopback or IP address and the certificate is issued for the deployment's name, or when the certificate is issued for an internal name (gdsgate join --enroll-sni). Unset with an IP address in endpoint, the certificate needs an IP entry; see Registration at an IP address.

[enroll]
endpoint       = "http://auth:50050"
renew_endpoint = "https://auth:50051"
state_dir      = "/var/lib/gdsgate/proxy"           # Windows: "C:\\ProgramData\\gdsgate\\state\\proxy"
# token is supplied at boot via GDSGATE_ENROLL_TOKEN

Registration token is single-use

Authority accepts a registration token once. The node then renews its persisted identity over mTLS without a token. Do not keep tokens in the file; supply them at first boot.

renew_endpoint requires the https:// scheme

Renewal is a mutual-TLS call. A renew_endpoint with another scheme is refused at start-up; gdsgate doctor reports it as config.enroll.renew_scheme. The same applies to [admin].endpoint. A node that receives an advertised renewal address with another scheme refuses it and logs the value.

Registration at an IP address

A TLS handshake to an IP address carries no server name. The join relay sends a connection without one to the control plane. A node registering at an https:// IP address therefore sends a fixed server name:

endpoint	transport_sni	Server name sent	Certificate checked against
https://<name>:<port>	unset	<name>	<name>
https://<ip>:<port>	unset	enroll.gdsgate.internal	<ip> (an IP entry)
https://<ip>:<port>	set	transport_sni	transport_sni
http://...	-	none, cleartext	-

enroll.gdsgate.internal routes the connection; a certificate from your own CA does not need it, and one the cluster CA issues (enroll_cert_from_cluster_ca) carries it. Renewal is unchanged: it sends gdsgate.internal.

A certificate the cluster CA issued is verified against that CA: transport_ca names it. gdsgate join --enroll-fingerprint reads it from the listener's chain, checks it against the fingerprint, and writes it beside the identity as <state_dir>/transport-ca.pem; setup prepare writes the Proxy's.

Node versions before this name reach the control plane when they register at an IP address through the join relay, and the registration fails. They can use transport_sni with a name the certificate carries, or an endpoint by name.

Automatic identity renewal

A transport certificate is valid for 24 hours, or for [transport].cert_ttl_secs on the issuing Authority. A Proxy or Connector renews it without a restart or a token:

Step	Behavior (24-hour certificate)
Start	One hour before expiry, the node calls renew_endpoint over mutual TLS with its current certificate.
Apply	The new certificate is written to state_dir and used for new connections and by the listeners. Open connections continue.
Timeouts	10 s for connect and handshakes, 20 s for the call.
Failure	Logged at warn, retried with backoff from 30 s to 10 min (about nine attempts within the hour). The node keeps using its current certificate.

These figures scale with the certificate lifetime; a shorter cert_ttl_secs shortens all of them. See [transport]. Renewal never falls back to a registration token.

background_renewal = false turns renewal off. The node then stops accepting new connections when its certificate expires, until it is restarted. Use it only when state_dir is refreshed by other means. gdsgate doctor warns while it is off.

Watch it through gdsgate_transport_identity_expires_in_seconds and gdsgate_transport_identity_renewals_total; see Operations → Metrics.