Horizontal Scaling for PostgreSQL Clusters with KubeBlocks

This guide explains how to perform horizontal scaling (scale-out and scale-in) on a PostgreSQL cluster managed by KubeBlocks. You'll learn how to use both OpsRequest and direct Cluster API updates to achieve this.

Prerequisites

Before proceeding, ensure the following:

• Environment Setup:
  • A Kubernetes cluster is up and running.
  • The kubectl CLI tool is configured to communicate with your cluster.
  • KubeBlocks CLI and KubeBlocks Operator are installed. Follow the installation instructions here.
• Namespace Preparation: To keep resources isolated, create a dedicated namespace for this tutorial:

kubectl create ns demo
namespace/demo created

Deploy a PostgreSQL Cluster

KubeBlocks uses a declarative approach for managing PostgreSQL clusters. Below is an example configuration for deploying a PostgreSQL cluster with 2 replicas (1 primary, 1 replicas).

Apply the following YAML configuration to deploy the cluster:

apiVersion: apps.kubeblocks.io/v1
kind: Cluster
metadata:
  name: pg-cluster
  namespace: demo
spec:
  terminationPolicy: Delete
  clusterDef: postgresql
  topology: replication
  componentSpecs:
    - name: postgresql
      serviceVersion: 16.4.0
      labels:
        apps.kubeblocks.postgres.patroni/scope: pg-cluster-postgresql
      disableExporter: true
      replicas: 2
      resources:
        limits:
          cpu: "0.5"
          memory: "0.5Gi"
        requests:
          cpu: "0.5"
          memory: "0.5Gi"
      volumeClaimTemplates:
        - name: data
          spec:
            accessModes:
              - ReadWriteOnce
            resources:
              requests:
                storage: 20Gi

Verifying the Deployment

Monitor the cluster status until it transitions to the Running state:

kubectl get cluster pg-cluster -n demo -w

Expected Output:

NAME         CLUSTER-DEFINITION   TERMINATION-POLICY   STATUS     AGE
pg-cluster   postgresql           Delete               Creating   50s
pg-cluster   postgresql           Delete               Running    4m2s

Once the cluster status becomes Running, your PostgreSQL cluster is ready for use.

Scale-out (Add Replicas)

Expected Workflow:

1. New pod is provisioned, and transitions from Pending to Running with secondary role
2. Data synced from primary to new replica
3. Cluster status changes from Updating to Running

apiVersion: operations.kubeblocks.io/v1alpha1
kind: OpsRequest
metadata:
  name: pg-cluster-scale-out-ops
  namespace: demo
spec:
  clusterName: pg-cluster
  type: HorizontalScaling
  horizontalScaling:
  - componentName: postgresql
    # Specifies the replica changes for scaling in components
    scaleOut:
      # Specifies the replica changes for the component.
      # add one more replica to current component
      replicaChanges: 1

kubectl get ops pg-cluster-scale-out-ops -n demo -w

NAME           TYPE                CLUSTER      STATUS    PROGRESS   AGE
pg-scale-out   HorizontalScaling   pg-cluster   Running   0/1        8s
pg-scale-out   HorizontalScaling   pg-cluster   Running   1/1        24s
pg-scale-out   HorizontalScaling   pg-cluster   Succeed   1/1        24s

apiVersion: apps.kubeblocks.io/v1
kind: Cluster
metadata:
  name: pg-cluster
  namespace: demo
spec:
  terminationPolicy: Delete
  clusterDef: postgresql
  topology: replication
  componentSpecs:
    - name: postgresql
      serviceVersion: 16.4.0
      labels:
        apps.kubeblocks.postgres.patroni/scope: pg-cluster-postgresql
      disableExporter: true
      replicas: 3 # increase replicas to scale-out
      resources:
        requests:
          cpu: "1"
          memory: "1Gi"
        limits:
          cpu: "1"
          memory: "1Gi"
      volumeClaimTemplates:
        - name: data
          spec:
            storageClassName: ""
            accessModes:
              - ReadWriteOnce
            resources:
              requests:
                storage: 20Gi

kubectl patch cluster pg-cluster -n demo --type=json -p='[{"op": "replace", "path": "/spec/componentSpecs/0/replicas", "value": 3}]'

Verify Scale-Out

After applying the operation, you will see a new pod created and the PostgreSQL cluster status goes from Updating to Running, and the newly created pod has a new role secondary.

kubectl get pods -n demo -l app.kubernetes.io/instance=pg-cluster

Example Output (3 Pods):

NAME                      READY   STATUS    RESTARTS   AGE
pg-cluster-postgresql-0   4/4     Running   0          13m
pg-cluster-postgresql-1   4/4     Running   0          12m
pg-cluster-postgresql-2   4/4     Running   0          5m5s

New replicas automatically join as secondary nodes.

kubectl get pods -n demo -l app.kubernetes.io/instance=pg-cluster -L kubeblocks.io/role

Example Output:

NAME                      READY   STATUS    RESTARTS   AGE     ROLE
pg-cluster-postgresql-0   4/4     Running   0          13m     primary
pg-cluster-postgresql-1   4/4     Running   0          12m     secondary
pg-cluster-postgresql-2   4/4     Running   0          5m54s   secondary

Scale-in (Remove Replicas)

Expected Workflow:

1. Selected replica (the one with the largest ordinal) is removed
2. If removing a primary replica, automatic switchover occurs first
3. Pod is terminated gracefully
4. Cluster status changes from Updating to Running

apiVersion: operations.kubeblocks.io/v1alpha1
kind: OpsRequest
metadata:
  name: pg-cluster-scale-in-ops
  namespace: demo
spec:
  clusterName: pg-cluster
  type: HorizontalScaling
  horizontalScaling:
  - componentName: postgresql
    # Specifies the replica changes for scaling in components
    scaleIn:
      # Specifies the replica changes for the component.
      # remove one replica from current component
      replicaChanges: 1

kubectl get ops pg-cluster-scale-in-ops -n demo -w

NAME           TYPE                CLUSTER      STATUS    PROGRESS   AGE
pg-scale-in   HorizontalScaling   pg-cluster   Running   0/1        8s
pg-scale-in   HorizontalScaling   pg-cluster   Running   1/1        24s
pg-scale-in   HorizontalScaling   pg-cluster   Succeed   1/1        24s

apiVersion: apps.kubeblocks.io/v1
kind: Cluster
metadata:
  name: pg-cluster
  namespace: demo
spec:
  terminationPolicy: Delete
  clusterDef: postgresql
  topology: replication
  componentSpecs:
    - name: postgresql
      serviceVersion: 16.4.0
      labels:
        apps.kubeblocks.postgres.patroni/scope: pg-cluster-postgresql
      disableExporter: true
      replicas: 1 # decrease replicas to scale-in
      resources:
        requests:
          cpu: "1"
          memory: "1Gi"
        limits:
          cpu: "1"
          memory: "1Gi"
      volumeClaimTemplates:
        - name: data
          spec:
            storageClassName: ""
            accessModes:
              - ReadWriteOnce
            resources:
              requests:
                storage: 20Gi

kubectl patch cluster pg-cluster -n demo --type=json -p='[{"op": "replace", "path": "/spec/componentSpecs/0/replicas", "value": 1}]'

Verify Scale-In

Example Output (ONE Pod):

kubectl get pods -n demo -l app.kubernetes.io/instance=pg-cluster
NAME                      READY   STATUS    RESTARTS   AGE
pg-cluster-postgresql-0   4/4     Running   0          16m

Best Practices

When performing horizontal scaling:

• Scale during low-traffic periods when possible
• Monitor cluster health during scaling operations
• Verify sufficient resources exist before scaling out
• Consider storage requirements for new replicas

Cleanup

To remove all created resources, delete the PostgreSQL cluster along with its namespace:

kubectl delete cluster pg-cluster -n demo
kubectl delete ns demo

Summary

In this guide you learned how to:

• Perform scale-out operations to add replicas to a PostgreSQL cluster.
• Perform scale-in operations to remove replicas from a PostgreSQL cluster.
• Use both OpsRequest and direct Cluster API updates for horizontal scaling.

KubeBlocks ensures seamless scaling with minimal disruption to your database operations. with minimal disruption to your database operations.