Restore a PostgreSQL Cluster from Backup

This guide demonstrates two methods to restore a PostgreSQL cluster from backup in KubeBlocks:

1. Cluster Annotation Method - Simple declarative approach using YAML annotations
2. OpsRequest API Method - Enhanced operational control with progress monitoring

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

Preparing for Restoration: Locate one Full Backup

Before restoring, ensure that there is a full backup available. The restoration process will use this backup to create a new PostgreSQL cluster.

• Backup repository accessible from new cluster
• Valid full backup in Completed state
• Adequate CPU/memory resources
• Sufficient storage capacity

Find available full backups:

kubectl get backup -n demo -l dataprotection.kubeblocks.io/backup-type=Full,app.kubernetes.io/instance=pg-cluster # get the list of full backups

Pick ONE of the Backups whose status is Completed.

Step 1: Create Restored Cluster

Create a new cluster with restore configuration:

Key parameters:

• kubeblocks.io/restore-from-backup annotation
• Backup name and namespace located from the previous steps

apiVersion: apps.kubeblocks.io/v1
kind: Cluster
metadata:
  name: pg-restored
  namespace: demo
  annotations:
    # NOTE: replcae <FULL_BACKUP_NAME> with the backup name
    kubeblocks.io/restore-from-backup: '{"postgresql":{"name":"<FULL_BACKUP_NAME>","namespace":"demo","volumeRestorePolicy":"Parallel"}}'
spec:
  terminationPolicy: Delete
  clusterDef: postgresql
  topology: replication
  componentSpecs:
    - name: postgresql
      serviceVersion: 16.4.0
      disableExporter: true
      labels:
        apps.kubeblocks.postgres.patroni/scope: pg-restored-postgresql
      replicas: 2
      resources:
        limits:
          cpu: "0.5"
          memory: "0.5Gi"
        requests:
          cpu: "0.5"
          memory: "0.5Gi"
      volumeClaimTemplates:
        - name: data
          spec:
            storageClassName: ""
            accessModes:
              - ReadWriteOnce
            resources:
              requests:
                storage: 20Gi

Step 3: Monitor Restoration

Track restore progress with:

# Watch restore status
kubectl get restore -n demo -w

# Watch cluster status
kubectl get cluster -n demo -w

Cleanup

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

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

Summary

This guide covered two restoration methods:

1. Cluster Annotation - Simple YAML-based approach

   • Retrieve system credentials
   • Create cluster with restore annotation
   • Monitor progress

2. OpsRequest API - Enhanced operational control

   • Create restore request
   • Track operation status
   • Verify completion