POST /registry/drainMarks a worker client (by clientId) as draining. Its sessions take no new placements; existing placements keep routing. With a deadline, the lease stops renewing past the deadline plus one lease, so the session dies and its ids re-place elsewhere.
The drain is stored per clientId, not per session: it applies while the worker is down and to every later registration with the same clientId. Register and heartbeat acks report it as draining and drainDeadline.
pinned generates a new clientId per process, so a restarted process is not drained. TODO(verify): whether that is intended.
Authentication
pinboard:operator scope. The client's last registration (namespaces, hostname, envs) must lie inside the claim. An unknown clientId answers 403.
Request body
application/json, at most 1 MiB.
| Field | Type | Required | Description |
|---|---|---|---|
clientId | string | Yes | From List workers. |
deadline | number | null | Yes | Seconds from now until forced release, floored to one lease. null cordons: drain with no deadline. |
A second drain replaces the first.
Example
curl -X POST https://pinboard.example.com/registry/drain \
-H "Authorization: Bearer $PINBOARD_OPERATOR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"clientId": "c1e0b7a94f6d4a1e9b2c3d4e5f60718a", "deadline": 300}'Response
200
| Field | Type | Description |
|---|---|---|
drained | true | Always true. |
{ "drained": true }A timed drain is kept 7 days past its deadline, then forgotten. A cordon is kept until undrain.
Errors
| Status | Body | When |
|---|---|---|
401 | {"error":"unauthorized"} | No accepted credential |
403 | {"error":"forbidden"} | No pinboard:operator scope, malformed claim, unknown clientId, or the client is outside the claim |
503 | {"error":"not the serving fleet"} | Node not serving |
413 / 400 | body too large / invalid json | |
400 | {"error":"expected { clientId, deadline }"} | Schema failure; deadline must be present |