opschain admin runner-group drain
Included from Basic tier
opschain admin runner-group drain <name>
Drains every runner of a group (the v2 RunnerService.SetRunnerGroupDraining RPC):
the group's runners finish the steps they already hold and are offered
nothing new. The drain is a single durable flag on the group — runners
enrolling into the group while it is draining are drained too — and stays
in force until opschain admin runner-group resume lifts it.
In admin runners list the group's runners show draining (group) or
quiesced (group) (or (runner+group) where a per-runner drain is also in
force); queued work that only this group could take parks with
every eligible runner is draining in the fleet queue.
The drain takes effect on every server replica within a dispatch tick: the group's parked polls are never matched to new work, so offers go straight to the undrained runners. Each idle member's poll is then held for the full poll window (50 s by default) and answered empty, so a drained group of any size costs one liveness write per runner per window rather than several requests a second per runner.
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
The server's acknowledgement, as JSON (-o yaml for YAML):
{
"draining": true,
"name": "secure"
}
An info:runner:group_drain_changed event records the change.
Exit codes
0 drained; 1 the request failed (unknown group, network, rejected token); 2 usage.
Named errors
a server is required — pass --server <url>, set OPSCHAIN_SERVER, or 'opschain context use <name>'(exit 2)this command needs a login or an admin token — run 'opschain login', pass --auth-token, set OPSCHAIN_ADMIN_TOKEN, or store one with 'opschain admin login'(exit 2)the server rejected the credential — run 'opschain login' again, or check the admin token(exit 1)- An unknown group name reports the server's 404 (exit 1).
See also
opschain docs cli/admin-runner-group-resume— lift the group drain.opschain docs cli/admin-runner-drain— drain one runner instead.opschain docs fleet-queue— draining in the verdict ladder, and the fleet-wide drain and quiesce levers beyond a single group.