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:

1. Secondary replicas update first
2. Primary updates last after secondaries are healthy
3. 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
      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.

Vertical Scale

Expected Workflow:

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

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

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

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

  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
        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:

1. Deploy a PostgreSQL cluster managed by KubeBlocks.
2. Perform vertical scaling by increasing or decreasing resources for the postgresql component.
3. 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.