> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Vertically Scale a ClickHouse Cluster

<Warning>
  **Experimental**

  The Vertical Scaling API is experimental and not yet recommended for
  production use. Its behavior and interface may change in future releases.
  Notably, ClickHouse server settings derived from the instance size (such
  as the SSD cache) are **not** recalculated when resources change. Review
  the [Limitations](#limitations) before using it.
</Warning>

Adjust CPU and memory resources for a ClickHouse cluster using the Private API.

## Prerequisites

* ClickHouse Private API installed and accessible (e.g., via port-forward to `http://localhost:8080/`)
* At least one ClickHouse cluster deployed (this guide uses `default-xx-01`)

## 1. Create the Scale Request

Create a JSON file with the desired resource allocation:

```json theme={null}
{
  "vertical": {
    "resources": {
      "cpu": "4",
      "memory": "16Gi"
    }
  }
}
```

Save this as `scale.json`.

## 2. Send the Request

```sh theme={null}
curl -X POST "http://localhost:8080/api/v1/instances/default-xx-01/scale" \
    -H "Content-Type: application/json" \
    --data-binary "@scale.json"
```

## 3. CPU:Memory Ratio Enforcement

The API enforces a **1:4 CPU to memory ratio** (1 CPU core per 4 GiB of memory) with a 5% margin.

If you provide only one resource type, the API automatically derives the other. For example, specifying only `"memory": "16Gi"` sets CPU to 4 cores.

The API sets `resources.requests` and `resources.limits` to the same value for both CPU and memory, so scaled pods stay in the [Guaranteed](https://kubernetes.io/docs/concepts/workloads/pods/pod-qos/) QoS class. If you want to run with a different QoS class, see [Pod QoS: Guaranteed (recommended)](/docs/cloud/clickhouse-private/reference/infrastructure-requirements#pod-qos-guaranteed-recommended).

**Accepted resource quantity formats:**

| Type   | Examples                                                |
| ------ | ------------------------------------------------------- |
| CPU    | `"4"` (cores), `"2.5"` (decimal), `"500m"` (millicores) |
| Memory | `"16Gi"` (gibibytes), `"4096Mi"` (mebibytes)            |

Binary units (Ki, Mi, Gi) are recommended for memory.

## 4. Monitor Scaling Progress

Check the cluster status to track the scaling operation:

```sh theme={null}
curl "http://localhost:8080/api/v1/instances/default-xx-01/status"
```

The response includes:

* `state`: Current cluster state
* `previousState`: State before the transition
* `message`: Details about the state transition

The scaling is complete when the cluster returns to a running state.

## Rolling Restart Behavior

The API updates the `ServerPodPolicy` of the `ClickhouseCluster` custom resource. The operator then performs a rolling restart of the StatefulSets with the new resource allocation.

> **Important:** Unlike ClickHouse Cloud, ClickHouse Private does not use [Make Before Break (MBB) scaling](https://clickhouse.com/docs/manage/scaling#how-scaling-works-in-clickhouse-cloud). Vertical scaling may cause brief service disruptions during the rolling restart.

## Limitations

* **Size-based server settings are not recalculated.** ClickHouse server settings that are derived from the instance size (for example, the SSD cache) are not automatically updated when you scale. After scaling, these settings retain the values computed for the original size, so a scaled cluster may not use the additional resources as expected. Adjust the affected settings manually if needed.
* **Service disruption during scaling.** Scaling triggers a rolling restart of the StatefulSets, which may cause brief service disruptions (see [Rolling Restart Behavior](#rolling-restart-behavior)).