opschain admin server node quiesce
Included from Basic tier
Durably drains ONE server node, named by its stable server name (the
server_name config key / OPSCHAIN_SERVER_NAME, default: the node's
hostname). The quiesced node: leaves readiness (/readyz answers 503 with
server_node: held, so the load balancer stops routing to it), stops
offering jobs to runners, hands its scheduler shards, cron leadership and
membership row back to its peers, and detaches its in-flight run drives —
peers adopt them within the staleness window and the runs continue
untouched. The rest of the estate keeps serving.
The node is then SAFE TO KILL, kill -9 included: every run is resumable
from the store. And because the posture is durable, the restarted (rolled)
binary boots HELD — fully healthy, logs and API inspectable, but taking no
work — until an operator issues
opschain admin server node resume <server-name>. Nothing resumes a held
node automatically.
Quiescing an already-held node is idempotent: the original posture row (and its recorded actor) stands. The verb also accepts a name that is not currently serving — the posture then pre-holds that node's next boot.
Each quiesce and resume is audited (info:server:node_quiesced /
info:server:node_resumed events carrying the server name and actor).
Flags
| Flag | Meaning |
|---|---|
--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 is the posture row — JSON, or YAML under -o yaml — plus a stderr
line naming the resume verb.
Exit codes
| Code | Meaning |
|---|---|
| 0 | Node quiesced (or already held). |
| 1 | Request failed or the token was rejected. |
| 2 | Usage error — no name, or no server/credential resolvable. |
Named errors
a server node name is required — the node's stable server_name (see 'admin server node list')— empty name (exit 1,invalid_argument).
Examples
# Roll node-a: drain it, kill it, roll the binary, inspect, resume.
opschain admin server node quiesce node-a
# ... kill -9, replace the binary, start it: it boots held ...
opschain admin server node resume node-a
See also
opschain docs cli/admin-server-node-resume— the human-gated resume.opschain docs cli/admin-server-node-list— what is held right now.opschain docs cli/admin-server-quiesce— hold the WHOLE fleet's dispatch instead of one node.