Authority configuration¶

Apply supported changes with gdsgate reload --role authority. See the reload matrix for settings that require restart and the treatment of existing sessions.

Paths in the tables are relative to [authority]. Keep keys and certificates in protected files. Check parsing and cross-field rules with gdsgate doctor --config <PATH> --json. See the multi-node control plane guide.

`[authority]`¶

Used by: Authority.

The certificate of the registration listener ([endpoints].authority_enroll), the emergency socket, CA seed wrapping, and agent declaration versioning. The control plane uses mutual TLS from the cluster transport CA and needs no settings here.

Key	Type	Default	Purpose
`node_advert`	table (optional)	unset	Shared node-facing addresses retained by HA join. Keeps the cluster enrollment/renewal entry and TLS settings consistent across Authorities. See retained endpoints.
`enroll_cert_file`	string	unset	PEM certificate chain the registration listener presents. Unset, the listener speaks cleartext h2c.
`enroll_key_file`	string	unset	PEM private key for `enroll_cert_file`. Setting only one of the pair is refused at start-up. Accepts a secret reference, resolved again on each certificate change.
`enroll_cert_from_cluster_ca`	bool	`false`	Authority issues the pair itself from the cluster CA and writes it to `enroll_cert_file` and `enroll_key_file` (both required; the key a plain path). See issued by the cluster CA. `false`: the files come from outside and are only read.
`emergency_socket`	string	unset	Path of the emergency administrative socket. Unset: no socket.
`ca_kms_key`	string (optional)	unset	The `[[kms_keys]]` entry that wraps the CA signing seeds.
`agent_declaration_version`	`"optional"` \| `"required"`	`"optional"`	Whether a rewrite of an agent declaration must name the version it was edited from. `optional` accepts a rewrite without one; `required` refuses it. A given version is always checked. See concurrent edits.

[authority]
enroll_cert_file = "/etc/gdsgate/enroll-fullchain.pem"
enroll_key_file  = "/etc/gdsgate/enroll-key.pem"

Provision tokens and workload platform tokens (IssueWorkloadIdentity / RenewWorkloadIdentity) cross this listener. Without a certificate they travel in cleartext. Set a certificate when the listener is reachable from an untrusted network.

With enroll_cert_from_cluster_ca = false, gdsgate does not obtain this certificate; an ACME client or a corporate CA writes the files. The listener re-reads them on change. See Renewing a listener certificate. One pair can serve this listener and [proxy].public_cert_file when one name fronts both.

Nodes register at	Certificate carries
a name (`https://gate.example.com:50064`)	that name
an IP address (`https://192.0.2.10:50064`)	that address as an `IP` entry
an IP address with `[enroll].transport_sni`	the `transport_sni` name
the Proxy's public port with `public_join`	the name the Proxy verifies; see there

A node registering at an IP address sends enroll.gdsgate.internal as the server name. The certificate does not need it. See Registration at an IP address.

Registration listener has no transitional mode

The listener serves either cleartext h2c or TLS. When enroll_cert_file takes effect, change every node's [enroll].endpoint from http:// to https:// in the same rollout. A node with the wrong scheme cannot connect.

Nodes that already hold an identity renew over the control plane and are not affected. The failure shows on a first registration or on a node that lost its state directory. Turning TLS off requires the reverse change.

Retained endpoints¶

join --role authority and join --role pair write [authority.node_advert] from the verified bootstrap settings. It contains the fleet's tunnel, WebSocket, public and renewal addresses, Authority route, front name and public TLS ownership. Every joined Authority returns these shared values when enrolling a node. Its individual listeners remain in [endpoints].

Keep this generated table with the Authority configuration. An incomplete or contradictory table fails validation. Existing configurations without it derive node-facing settings from their endpoint, Proxy and Connector sections.

Issued by the cluster CA¶

For a gateway reached by IP address. setup prepare sets it when registration is dialled by address and no --enroll-cert is given; see setup prepare.

[authority]
enroll_cert_from_cluster_ca = true
enroll_cert_file = "/var/lib/gdsgate/authority/enroll.pem"
enroll_key_file  = "/var/lib/gdsgate/authority/enroll.key"

Item	Value
Issuer	The cluster transport CA. Its fingerprint is `transport_ca.fingerprint`, the value of `gdsgate connect --fingerprint`.
Names	The hosts of `[endpoints].proxy_public` and `proxy_join`; the host of `authority_enroll`, or `127.0.0.1` (and `::1` for `[::]`) where it is a wildcard; `enroll.gdsgate.internal`.
File	The leaf, then the cluster CA. The key is written owner-only.
Validity	90 days.
Issued again	At start and hourly while running, when the file is missing or unreadable, lacks a name, was issued by a CA that is no longer active, the key does not parse or match the certificate, or it expires within 30 days. The listener picks up the new pair within a second.
Log	`registration certificate issued from the cluster CA`; on failure `registration certificate not issued; the one in force stays in force`.
Checks	`config check` and `doctor` report the pair under `authority.enroll_cert_from_cluster_ca`: not issued yet, a missing name, inside the renewal window (warning), expired (error).

Peers verify it against the cluster CA: a connector with gdsgate join --enroll-fingerprint, the Proxy with [enroll].transport_ca.

The emergency administrative socket¶

[authority]
emergency_socket = "/run/gdsgate/auth-emergency.sock"

Unset by default: no socket.

Use it when the policy refuses everybody, including the administrative certificate. The socket is reachable only on the Authority host.

	Linux	Windows
Object	Unix socket, mode `0600`. Start-up is refused if another account can reach it.	Named pipe with an access list of its owner, `SYSTEM` and administrators. Start-up fails if another process already holds the name.
Directory	Created `0700` if absent; an existing directory is not changed. A directory writable by other accounts is refused.	None.
Accepted callers	The socket owner and `root`.	The pipe owner, `SYSTEM`, and elevated administrators.
`gdsgate doctor`	Reports the socket, its mode, and the directory.	Reports whether the pipe is served.

On Linux, point the key at a directory owned by the service account. The shipped systemd unit has a commented RuntimeDirectory=gdsgate / RuntimeDirectoryMode=0700 pair; uncomment it to get the path above.

Calls on the socket carry no identity, token or address; a call that offers one is refused. Cedar decides them as User::"gdsgate-break-glass", the principal every accepted policy must keep able to edit the policy. Other actions are allowed only if a rule names them; the shipped baseline names none.

The socket serves PullPolicy, PushPolicy, the catalog calls and the registry listings, and refuses other methods. Its audit rows name gdsgate-break-glass as the actor and carry admin_channel=emergency-socket. Walkthrough: Lock-out and recovery.

gdsgate doctor findings for registration:

Finding	Reports
`config.authority.enroll_listener`	Whether the registration listener uses TLS or cleartext.
`config.enroll.trust`	Which mode a node is configured for.
`config.proxy.join_relay`	How registration crosses the join relay, when bound.
`config.proxy.public_join`	Whether `public_join` is on, with its call budget and lane limits.

Wrapping the CA signing seeds¶

[authority]
ca_kms_key = "ca"

Unset: each CA seed is stored as 32 plain bytes in the database column ca_private_key.seed. Set: seeds written from then on are stored as ciphertext. A seed is unwrapped when its generation is loaded (at start-up and when a rotation publishes a new one). Signing a certificate does not unwrap it.

The value is the name of a [[kms_keys]] entry. Each row records the fingerprint of its wrapping key. Starting with a different key is refused; the error names both keys. Plain rows are still read; gdsgate authority ca seeds wrap converts them. A partly converted table works.