Vertical Scaling for PostgreSQL Clusters with KubeBlocks

This guide demonstrates how to vertically scale a PostgreSQL cluster managed by KubeBlocks by adjusting compute resources (CPU and memory) while maintaining the same number of replicas.

Vertical scaling modifies compute resources (CPU and memory) for PostgreSQL instances while maintaining replica count. Key characteristics:

Non-disruptive: When properly configured, maintains availability during scaling
Granular: Adjust CPU, memory, or both independently
Reversible: Scale up or down as needed

KubeBlocks orchestrates scaling with minimal impact:

Secondary replicas update first
Primary updates last after secondaries are healthy
Cluster status transitions from Updating to Running

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.

TIP

If you are creating the cluster for the very first time, it may take some time to pull images before running.

Vertical Scale

Expected Workflow:

Secondary replicas are updated first (one at a time)
Primary is updated last after secondary replicas are healthy
Cluster status transitions from Updating to Running

Option 1: Using VerticalScaling OpsRequest

Apply the following YAML to scale up the resources for the postgresql component:

apiVersion: operations.kubeblocks.io/v1alpha1
kind: OpsRequest
metadata:
  name: pg-cluster-vscale-ops
  namespace: demo
spec:
  clusterName: pg-cluster
  type: VerticalScaling
  verticalScaling:
  - componentName: postgresql
    requests:
      cpu: '1'
      memory: 1Gi
    limits:
      cpu: '1'
      memory: 1Gi

What Happens During Vertical Scaling?

Secondary Pods are recreated first to ensure the primary Pod remains available.
Once all secondary Pods are updated, the primary Pod is restarted with the new resource configuration.

You can check the progress of the scaling operation with the following command:

kubectl -n demo get ops pg-cluster-vscale-ops -w

Expected Result:

NAME                    TYPE              CLUSTER      STATUS    PROGRESS   AGE
pg-cluster-vscale-ops   VerticalScaling   pg-cluster   Running   0/2        52s
pg-cluster-vscale-ops   VerticalScaling   pg-cluster   Running   1/2        64s
pg-cluster-vscale-ops   VerticalScaling   pg-cluster   Running   2/2        2m6s
pg-cluster-vscale-ops   VerticalScaling   pg-cluster   Running   2/2        2m6s
pg-cluster-vscale-ops   VerticalScaling   pg-cluster   Succeed   2/2        2m6s

Option 2: Direct Cluster API Update

Alternatively, you may update spec.componentSpecs.resources field to the desired resources for vertical scale.

  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:
          requests:
            cpu: "1"       # Update the resources to your need.
            memory: "1Gi"  # Update the resources to your need.
          limits:
            cpu: "1"       # Update the resources to your need.
            memory: "1Gi"  # Update the resources to your need.
        volumeClaimTemplates:
          - name: data
            spec:
              storageClassName: ""
              accessModes:
                - ReadWriteOnce
              resources:
                requests:
                  storage: 20Gi

Best Practices & Considerations

Planning:

Scale during maintenance windows or low-traffic periods
Verify Kubernetes cluster has sufficient resources
Check for any ongoing operations before starting

Execution:

Maintain balanced CPU-to-Memory ratios
Set identical requests/limits for guaranteed QoS

Post-Scaling:

Monitor resource utilization and application performance
Consider adjusting PostgreSQL parameters if needed

Verification

Verify the updated resources by inspecting the cluster configuration or Pod details:

kbcli cluster describe pg-cluster -n demo

Expected Output:

Resources Allocation:
COMPONENT    INSTANCE-TEMPLATE   CPU(REQUEST/LIMIT)   MEMORY(REQUEST/LIMIT)   STORAGE-SIZE   STORAGE-CLASS
postgresql                       1 / 1                1Gi / 1Gi               data:20Gi      standard

Key Benefits of Vertical Scaling with KubeBlocks

Seamless Scaling: Pods are recreated in a specific order to ensure minimal disruption.
Dynamic Resource Adjustments: Easily scale CPU and memory based on workload requirements.
Flexibility: Choose between OpsRequest for dynamic scaling or direct API updates for precise control.
Improved Availability: The cluster remains operational during the scaling process, maintaining high availability.

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:

Deploy a PostgreSQL cluster managed by KubeBlocks.
Perform vertical scaling by increasing or decreasing resources for the postgresql component.
Use both OpsRequest and direct Cluster API updates to adjust resource allocations.

Vertical scaling is a powerful tool for optimizing resource utilization and adapting to changing workload demands, ensuring your PostgreSQL cluster remains performant and resilient.