opschain admin platform quiesce

Included from Basic tier

opschain admin platform quiesce --reason <text> [--timeout <duration>] [--server <url>] [--auth-token <token>]

Quiesces the entire OpsChain system for maintenance via the v2 PlatformService.StartSystemQuiesce call: the estate drains first, then holds read-only. Entry immediately stops the schedulers and trigger firing estate-wide and withholds new leases from the runner and agent planes; running jobs run to completion. The command waits, printing drain progress (draining: N attempt(s) still running) to stderr; when the last running attempt finishes the write barrier closes:

• every mutating API request (POST/PUT/PATCH/DELETE under /api and /admin, and every mutating v2 procedure) answers 503 system quiesced for maintenance: <reason> — except the quiesce, halt and verify-restore verbs themselves, which stay admitted so the estate can always be resumed;
• new credential logins are refused — existing tokens keep reading, and the session refresh rotation (AuthService Refresh) still works;
• retention and the database-maintenance loops stop;
• reads, /readyz and /api/info stay up and report the state (checks.system_quiesce and the quiesce info attribute).

The posture is a durable row honoured by every replica — it survives restarts and failovers, and there is no auto-resume: the system stays read-only until an explicit opschain admin platform resume (bare, no flags). The quiesced state is the precondition the backup and export lanes verify before they run.

The emergency halt is orthogonal: admin platform halt (and its per-plane resume) still works against a quiesced estate.

Flags

Flag	Meaning
--reason <text>	Maintenance reason (required) — named on every refused write's 503 and on the audit events.
--timeout <duration>	Bound the drain wait (e.g. 15m). On expiry the attempt aborts cleanly back to fully active — never a half-state — and the command exits non-zero naming the still-running work. 0 (the default) waits indefinitely.
--server <url>	Server base URL (default: the active context / OPSCHAIN_SERVER).
--auth-token <token>	Admin bearer token override (default: your opschain login session, then $OPSCHAIN_ADMIN_TOKEN, then the token stored by opschain admin login).

Output

Progress lines go to stderr while draining; the final machine document (the posture, phase and attempt counts) prints on stdout:

draining: 2 attempt(s) still running
draining: 1 attempt(s) still running
system quiesced: the write barrier is closed — resume with 'opschain admin platform resume'
{"posture":{"id":"ocsq_…","reason":"monthly backup",…},"phase":"quiesced","remaining_attempts":0,"attempts":[]}

Audit events

• api:platform:quiesced — the barrier closed (posture id, reason, actor).
• api:platform:resumed — the explicit resume reopened writes.
• warn:platform:quiesce_aborted — a --timeout expiry aborted the drain, naming the attempts that were still running.

Named errors

• a reason is required — 422; the verb is audited and the reason is shown to every refused caller.
• quiesce aborted after <timeout>: the system is fully active again; N attempt(s) were still running: … — the non-zero timeout exit.
• the system is already quiesced: the drain completed — resume with 'opschain admin platform resume' — 409 from the abort endpoint when the barrier closed as the timeout fired; the CLI treats this as success.

See also: admin platform resume, admin platform status, admin platform halt, admin database.