Skip to main content
Use this runbook when bundled ClickHouse needs more PVC capacity. This applies to ClickHouse created by the metoro-onprem chart and managed by the Altinity ClickHouse Operator. If ClickHouse is externally managed, resize storage through the team and tooling that operate that ClickHouse service. The Metoro chart does not manage external ClickHouse PVCs.

​
What To Change

The clickhouse.bundled.storage Helm value controls the ClickHouse data PVC size per replica. The chart renders this into the metoro-default-storage volume claim template on the ClickHouseInstallation named metoro. In hot PVC plus object storage deployments, this value is the hot PVC size per ClickHouse replica. In PVC-only deployments, this value is the full retained ClickHouse PVC size per replica. Increase the value in metoro-hub-values.yaml: 
clickhouse:
  bundled:
    storage: 200Gi
Use a value larger than the current PVC size. Kubernetes PVCs normally support expansion, not shrinking.

​
Prerequisites

Before applying the change, confirm:
  • The ClickHouse StorageClass supports volume expansion, for example allowVolumeExpansion: true.
  • The StorageClass is retained and network attached so ClickHouse pods can move between nodes while keeping their PVCs.
  • The backing storage provider has enough free capacity for every ClickHouse replica.
  • The new size is larger than the current ClickHouse PVC size.
You can check the StorageClass used by ClickHouse with: 
kubectl -n metoro-hub get pvc
kubectl get storageclass

​
Apply The Change

Apply the updated values with the same Helm release and chart version used for the hub: 
helm upgrade --install metoro oci://quay.io/metoro/charts/metoro-onprem \
  --namespace metoro-hub \
  --version 10.0.1 \
  --values metoro-hub-values.yaml

​
What Happens

After the Helm upgrade, the ClickHouseInstallation named metoro updates its metoro-default-storage volume claim template to the new size. The Altinity ClickHouse Operator reconciles the updated ClickHouseInstallation and updates the ClickHouse PVC requests. Kubernetes and the storage provider then expand each PVC. Depending on the CSI driver and filesystem expansion behavior, ClickHouse pods may keep running while the filesystem grows, or pods may restart so the larger filesystem is visible inside the container. If restarts are needed, expect the operator to process ClickHouse pods one at a time rather than restarting all replicas together. During the rollout, Apiserver and Ingester may briefly observe ClickHouse replica readiness changes. They should continue operating and recover automatically as ClickHouse replicas return to ready state.

​
Verify The Rollout

Check that the ClickHouseInstallation exists and is being reconciled: 
kubectl -n metoro-hub get chi metoro
Confirm the desired CHI storage value matches the new Helm value: 
kubectl -n metoro-hub get chi metoro \
  -o jsonpath='{.spec.templates.volumeClaimTemplates[0].spec.resources.requests.storage}{"\n"}'
Watch the PVCs and confirm the ClickHouse data PVCs show the larger requested capacity: 
kubectl -n metoro-hub get pvc
Watch the ClickHouse pods while the operator reconciles: 
kubectl -n metoro-hub get pods -l app=metoro-clickhouse -w
The expected outcome is:
  • The CHI desired storage value matches clickhouse.bundled.storage.
  • ClickHouse PVCs show the larger requested capacity.
  • ClickHouse pods remain ready, or restart one at a time if the storage driver requires a remount or filesystem expansion on restart.
  • Apiserver and Ingester recover automatically if any ClickHouse replica briefly becomes unavailable.
Do not manually patch ClickHouse PVCs as the normal workflow. Keep metoro-hub-values.yaml as the source of truth and let Helm, the ClickHouseInstallation, and the Altinity ClickHouse Operator reconcile the change.