runner.pool-rotate

Drain every alive runner instance in a warm-pool group + nudge the per-group reconcile workflow so the controller re-launches to the floor on its next tick. Use for AMI rotation / hygiene-config rollout / emergency replacement.

Drain the pool then nudge the controller reconcile workflow to re-provision up to min_warm_idle.

The semantic distinction from pool-drain: this workflow is explicit about the intent to replace. The drain step is identical; the trailing reconcile nudge immediately starts the controller re-launching fresh instances instead of waiting for the next 30s cron tick. Use when rotating to a new AMI / hygiene config / runtime — the old pool drains, the new one starts up in parallel.

Overview

Property	Value
Workflow type	Atomic
Library	App-runners
Version	1.0

Input Schema

Field	Type	Required	Default	Description
runner_group_uuid	uuid	Yes	—	UUID of the RunnerGroup to drain and rotate, picked from the organization's list of runner groups.
reason	string	No	—	—
workflow_run_id	string	No	—	DAG parent run ID (stamped by engine)

Output Schema

Field	Type	Required	Default	Description
runner_group_uuid	uuid	No	—	UUID of the RunnerGroup that was drained and rotated, echoed from input on output.
drained_count	integer	No	—	—
drain_errors	list	No	—	—
scale_check_started	boolean	No	—	—
scale_check_error	string	No	—	—
outcome	string	No	—	—
status	string	No	—	—
completed_at	string	No	—	—
failure_reason	string	No	—	—
failure_type	string	No	—	—
failed_action	string	No	—	—
failed_at_state	string	No	—	—
failed_step	string	No	—	—
failed_layer	string	No	—	—
error	string	No	—	—
error_type	string	No	—	—
reason	string	No	—	—
workflow_run_id	string	No	—	DAG parent run ID (stamped by engine)

States

State	Initial	Terminal	Success	Auto-advance	Description
pending	Yes	No	—	rotate	—
completed	No	Yes	Yes	—	—
failed	No	Yes	No	—	—

State Diagram

Transitions

From	Action	To	Description
pending	rotate	completed	—
* (any state)	fail	failed	—

API Usage

POST /api/workflows/start
Content-Type: application/json

{
  "workflow_type": "runner.pool-rotate",
  "initial_data": {
    "runner_group_uuid": "value"
  }
}