Authority configuration

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
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.

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 keys wrap-ca-seeds converts them. A partly converted table works.