# Change or delete a runner pool

Change a pool's labels, sizes, spare machines, machine reuse or image, or delete it and its machines.

Replace pool-id with the pool's id.

## Prerequisites

- `ci:UpdateRunnerPool` to change a pool, `ci:DeleteRunnerPool` to delete one, both on all of CI
  (`rn:ews::<organization id>:ci:*`). Without them the pool's row menu says
  "Needs ci:UpdateRunnerPool" or "Needs ci:DeleteRunnerPool".
- In the console, also `ci:DescribeRunners` to open **Runners** (without it the page shows an
  access-denied notice) and `ci:DescribeRunnerPools` to see **Runner pools** on it.

## Change the pool

A pool's name and machine size cannot be changed; create another pool for another size.

**Console**
1. Open **Runners** under CI.
2. Under **Runner pools**, in the pool's row menu, choose **Edit pool**.
3. Change **Labels**, **Always on**, **At most**, **Spare**, **Machine reuse** or
   **Pre-built runner image**.
4. Choose **Save pool**.

**CLI**
```sh
dcloud ci runner-pools update pool-id --max-size 20 --spare 1
```

**API**
```http
PATCH /ci/api/runner-pools/pool-id
{ "maxSize": 20, "spare": 1 }
```

A field you leave out keeps its value; new `labels` replace the old ones.

New sizes reach the pool's auto scaling group at once and the pool is rescaled. A changed
**Pre-built runner image** setting reaches the launch template on the next scaling pass; machines
already running keep what they booted.

- `400` "minSize 3 is above maxSize 2" when the sizes end up the wrong way round.
- `400` "A Linux machine cannot carry the label macos-latest: it would be sent macOS jobs."
- `400` when the body changes nothing.

## Delete the pool

**Console**
1. Open **Runners** under CI.
2. Under **Runner pools**, in the pool's row menu, choose **Delete pool**.
3. Choose **Delete**.

**CLI**
```sh
dcloud ci runner-pools delete pool-id
```

**API**
```http
DELETE /ci/api/runner-pools/pool-id
```

The answer is `200` with the pool's status `deleting`. The pool takes no more jobs, its auto
scaling group is set to zero machines, and the group, the launch template and the machines are
removed in the background.

## Related

- [Create a runner pool](create-a-runner-pool.md)
- `ci.runner-pools.update` · `ci.runner-pools.delete`
