Skip to main content
Use this runbook when you need to change the number of bundled PostgreSQL instances managed by the metoro-onprem chart and CloudNativePG. If PostgreSQL is externally managed, scale instances through the team and tooling that operate that PostgreSQL service. The Metoro chart does not manage external PostgreSQL instances. This page uses CloudNativePG terminology: a PostgreSQL cluster has instances. One instance is primary and the remaining instances are standbys.

​
What To Change

The postgres.bundled.cluster.instances Helm value controls the PostgreSQL instance count. The chart renders this into spec.instances on the CloudNativePG Cluster named metoro-postgresql. Change the value in metoro-hub-values.yaml: 
postgres:
  bundled:
    cluster:
      instances: 3
Keep metoro-hub-values.yaml as the source of truth. Do not manually edit the CloudNativePG Cluster for normal instance scaling.

​
When To Scale

Metoro normally runs bundled PostgreSQL with 3 instances in production. CloudNativePG runs one primary and uses the other instances as standbys for high availability and switchovers. Scale up when you are moving toward the recommended three-instance production shape or restoring instance count after a temporary downscale. Each added instance needs its own CPU, memory, PGDATA PVC, and optional WAL PVC. The minimum instance count is 1. A single-instance deployment has no standby to promote, so planned maintenance and node failures can become PostgreSQL outages. Scale down only when you accept reduced high availability and read capacity. Downscaling can reduce running pod cost, but CloudNativePG may remove instance resources and PVCs under its control. Storage cost may not drop cleanly or immediately depending on the StorageClass reclaim policy and retained PV behavior. Do not manually delete PostgreSQL PVCs or PVs as part of the normal scale runbook.

​
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 When Scaling Up

After the Helm upgrade, the CloudNativePG Cluster named metoro-postgresql updates its desired instance count. CloudNativePG creates additional PostgreSQL instance pods and PVCs. New standby instances initialize from the primary and catch up with replication. Catch-up can temporarily increase primary load, disk IO, WAL volume, network traffic, and backup/storage activity. Existing instances should generally continue serving the hub while new standbys come online.

​
What Happens When Scaling Down

After the Helm upgrade, the CloudNativePG Cluster named metoro-postgresql lowers its desired instance count. CloudNativePG removes surplus PostgreSQL instance resources. This reduces high availability and may remove standby capacity that would otherwise be used for failover, switchovers, and maintenance. Production deployments should normally stay at 3 instances. Downscale only when the operational tradeoff is understood.

​
Verify The Rollout

Check that the CloudNativePG cluster exists and is being reconciled: 
kubectl -n metoro-hub get cluster.postgresql.cnpg.io metoro-postgresql
Confirm the desired instance count matches the new Helm value: 
kubectl -n metoro-hub get cluster.postgresql.cnpg.io metoro-postgresql \
  -o jsonpath='{.spec.instances}{"\n"}'
Watch PostgreSQL pods and roles while CloudNativePG reconciles: 
kubectl -n metoro-hub get pods -l cnpg.io/cluster=metoro-postgresql \
  -L cnpg.io/instanceRole -w
Check PostgreSQL PVCs: 
kubectl -n metoro-hub get pvc -l cnpg.io/cluster=metoro-postgresql
Check recent events if pods or PVCs are slow to converge: 
kubectl -n metoro-hub get events --sort-by='.lastTimestamp'
The expected outcome is:
  • The CloudNativePG cluster desired instance count matches postgres.bundled.cluster.instances.
  • Scale-up creates new PostgreSQL standby pods and PVCs.
  • Scale-down removes surplus PostgreSQL instance resources and reduces high availability.
  • Existing PostgreSQL instances generally stay ready, though readiness may briefly change during reconciliation.
  • Apiserver and Temporal recover automatically if PostgreSQL readiness briefly changes.