Transport configuration

The flat configuration hub remains the compatibility route. This page is the canonical source-checked field reference for its family, including nested tables and list rows.

Paths in the tables are relative to [transport]. Each row gives the serde type and source default or unset meaning. Check parsing and transport cross-field rules with gdsgate doctor --config <PATH> --json, then follow the registration and CA guide.

[transport]

Used by: Authority, Proxy, Connector.

How long an issued node transport certificate lives, and what this cluster calls itself where several of them share one front.

Key	Type	Default	Purpose
cert_ttl_secs	int	86400	Validity of an issued transport leaf, in seconds. Minimum 120. Read on Authority.
front_sni	string	unset	The name this cluster answers to on a front that carries several clusters. Unset, nothing is added to a certificate and nothing is asked for on a hop. See The name a shared front routes on.

[transport]
cert_ttl_secs = 86400
# front_sni = "acme-proxy.gate.example.com"

Authority stamps the validity window on every leaf it signs, covering a first registration, a token-less renewal, and its own self-issued leaf, so cert_ttl_secs is set on the Authority host and not on the nodes. Every renewal timing on the node side is a share of this value, so changing it moves all of them at once.

	24 h (default)	3 min
Renewal starts with	1 h left	90 s left
Sleep between looks, at most	5 min	11 s
One attempt may take	30 s	11 s
Backoff after a failure	30 s to 10 min	11 s to 22 s
Calls to Authority per node	about 1 per day	about 1 per 90 s

Certificate TTL and renewal load

At three minutes each node renews roughly every ninety seconds, and every renewal is a mutual-TLS handshake, a CA signature and a durable audit write on Authority, and in HA on the write-leader. A thousand nodes at that setting is around eleven renewals a second, permanently. It is a setting for a test cluster that wants to watch a full renewal cycle, not for a fleet.

It is also a shorter grace period for an Authority outage: whatever is left of the leaf when renewal starts is the entire budget for Authority being unreachable. At the default that is an hour; at three minutes it is ninety seconds.

Authority refuses to start on a value below 120, and says why. Renewal sizes one attempt off the window, and below two minutes that share drops under five seconds, less than a control plane that is merely busy needs for a handshake, a CSR check, a CA signature and an audit commit. A fleet configured that way would time out its own renewals and expire without anything having reported an error.

Other certificate lifetimes are configured separately and are unaffected: workload certificates ([workload].cert_ttl_secs), the User SSH and Onward SSH certificates, and the CA generations themselves ([ca_rotation]).

The name a shared front routes on

A front standing in front of several clusters tells them apart by the name in the TLS hello. On the client-facing and registration ports that works, because the hello carries the cluster's own public name. On the two hops a node opens inwards, a connector's reverse tunnel and every node's token-less renewal, it does not: those ask for an internal transport name, tunnel.gdsgate.internal and proxy.gdsgate.internal, and the internal names are the same strings in every cluster. That is what makes them work as pins inside a cluster and useless outside one, since such a front sees the same hello from everybody and either sends everybody to one cluster or refuses everybody.

front_sni is the name a cluster answers to there. The value is a name, not an address: what a front reads out of a hello. In practice it is this cluster's own gateway name, because that is the name that resolves to the front.

Both sides of one cluster read the one key. Authority binds it into the transport leaf of every role that terminates TLS, beside the role names and never instead of them, so a node pinning the shared name or a role name verifies exactly the certificate it verified before. A node asks for it on the hops above, and a connector on both legs of its tunnel, gRPC and WebSocket, since a front routing by name would otherwise put the pair in two different places.

Nobody types it on the nodes. Authority advertises it on the exchange that issues a node's identity, and gdsgate join renders it into the [transport] section of the file it writes; see What Authority tells a joining node. Set it on Authority first: until the leaves carry the name, a node that asks for it is answered with a certificate that does not hold it, and the handshake fails.

Unset, which is every deployment written before the key existed, neither side does anything differently.

Changing front_sni on a running cluster

A node asks for the name it started with and goes on asking for it: the background loop renews the leaf, and does not rewrite configuration under a running process. Change it on Authority, then re-run gdsgate join --if-missing on each node, which rewrites the file and reports that a restart is needed, without performing one.