---
title: "Replace Cluster Control Plane"
method: POST
path: "/admin/clusters/{cluster_id}/replace-control-plane"
tags: ["admin"]
---

# Replace Cluster Control Plane

`POST /admin/clusters/{cluster_id}/replace-control-plane`

## Request

- Base URL: `https://api.mengi.cloud` (the document declares no server; this is the origin it was published from)
- URL: `https://api.mengi.cloud/admin/clusters/{cluster_id}/replace-control-plane`
- Auth: none declared

Replace a Hetzner cluster's control-plane servers with another type, one at a time.

Only for production-tier clusters, which run 3 control-plane servers:
replacing one leaves the other two (etcd quorum). Management clusters are
refused because their control-plane nodes need 8 GB or more. The cluster
goes to UPGRADING before the job is queued, so drift, rollovers and
autoscaling changes leave the stack alone until the worker finishes.

A replacement the worker stopped stays UPGRADING (its status message
starts with "Control-plane replacement stopped"). Calling this again
re-queues it without unlocking the stack; the worker resumes where it
stopped. If the job died without recording that (a worker crash), `force`
re-queues any replacement still marked UPGRADING, unless BullMQ still holds
a replacement job for the cluster (queued, running or awaiting a retry).

## Path parameters

- `cluster_id` string, uuid, required

## Request body

- ControlPlaneReplacementRequest
  - `server_type` string, required
  - `force` boolean

## Response `200`

Successful Response

- unknown

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/mengi/apis/mengi-cloud.md) · [All operations](https://skmtc.dev/mengi/apis/mengi-cloud/llms.txt) · [OpenAPI document](https://skmtc.dev/mengi/apis/mengi-cloud/revisions/4ae9b375cdbb?raw)