Sanity runbook

Operational sanity checks

Procedure gate

Gate	Contract
Classification	Read-only
Prerequisites	The exact binary and config files, an operator identity, protected metrics address if configured, and a non-destructive test resource.
Owner	The change operator before and after a rollout.
Approval	None for the checks; approval is required before using a production resource for a controlled session.
Backup point	Preserve the pre-change version, doctor report, metric snapshot, policy version, catalog listing, and audit cursor.
Command or check	Run the shell checklist below, replacing only deployment placeholders outside the committed documentation.
Expected status and exit	gdsgate --version, config doctor, policy validation, and node health exit 0; /healthz is 200; /readyz is 200 only after the role sets readiness; the controlled session opens and closes.
Stop condition	Stop the rollout on any non-zero command, missing persistent state, readiness 503 after the role's startup milestone, policy or catalog mismatch, registration refusal, or missing audit evidence.
Recovery	Keep traffic closed, compare the post-check result with the saved pre-change record, and use the relevant change or resilience procedure.
Rollback	Restore the last verified artifact and persistent state without deleting audit or migration rows.
Escalation	Route each failure to release, configuration, Authority, Connector, Proxy, database, or security ownership.

Run these checks before and after a planned change. They are deliberately separate from liveness: a process can answer /healthz with 200 while its role has not set readiness or while a Connector has no active tunnel.

set -euo pipefail

CONFIG="<config-file>"
POLICY="<policy-file>"
METRICS_ADDR="<metrics-host>:<metrics-port>"

gdsgate --version
gdsgate --config "$CONFIG" doctor
gdsgate --config "$CONFIG" authority policy validate "$POLICY"
curl -sS -o /dev/null -w '%{http_code}\n' "http://${METRICS_ADDR}/healthz"
curl -sS -o /dev/null -w '%{http_code}\n' "http://${METRICS_ADDR}/readyz"
gdsgate --config "$CONFIG" authority list-nodes --health

For a role without an Authority client, use the role's configured doctor and HTTP checks and mark the node-health command not applicable. For a Connector, also compare the Proxy's gdsgate_active_connector_tunnels and registration refusal counters with the expected fleet. For a controlled session, use a non-sensitive test resource, then verify the corresponding session.open and session.close evidence with the audit procedure. Do not invent a chain-depth or CA-rotation metric: those are not emitted source signals.