Skip to main content
ExperimentalThe 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 before using it.
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:
Save this as scale.json.

​
2. Send the Request

​
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 QoS class. If you want to run with a different QoS class, see Pod QoS: Guaranteed (recommended). Accepted resource quantity formats: Binary units (Ki, Mi, Gi) are recommended for memory.

​
4. Monitor Scaling Progress

Check the cluster status to track the scaling operation:
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. 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).
Last modified on August 7, 2026