Create a Full Backup for PostgreSQL on KubeBlocks

This guide demonstrates how to create and validate full backups for PostgreSQL clusters on KubeBlocks using the pg-basebackup method through both:

• The Backup API (direct backup operations)
• The OpsRequest API (managed backup operations with enhanced monitoring)

We will cover how to restore data from a backup in the Restore From Full Backup guide.

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.

Backup Prerequisites

Before creating backups, ensure:

1. Backup repository is configured:

   • BackupRepo resource exists
   • Network connectivity between cluster and repository
   • BackupRepo status shows "Ready"

2. Cluster is ready:

   • Cluster status is "Running"
   • No ongoing operations (scaling, upgrades, etc.)

Identify Backup Configuration

Check available backup policies and schedules:

# List backup policies
kubectl get backuppolicy -n demo -l app.kubernetes.io/instance=pg-cluster

# List backup schedules
kubectl get backupschedule -n demo -l app.kubernetes.io/instance=pg-cluster

Expected Output:

NAME                                            BACKUP-REPO   STATUS      AGE
pg-cluster-postgresql-backup-policy                           Available   58m

NAME                                              STATUS      AGE
pg-cluster-postgresql-backup-schedule             Available   60m

View supported backup methods in the BackupPolicy CR 'pg-cluster-postgresql-backup-policy':

kubectl get backuppolicy pg-cluster-postgresql-backup-policy -n demo -oyaml | yq '.spec.backupMethods[].name'

Example Output:

pg-basebackup
wal-g
wal-g-incremental
archive-wal
wal-g-archive

List of Backup methods

KubeBlocks PostgreSQL supports these backup methods:

Backup via Backup API

1. Create On-Demand Backup

The pg-basebackup method uses PostgreSQL's native pg_basebackup utility.

Apply this manifest to create a backup:

apiVersion: dataprotection.kubeblocks.io/v1alpha1
kind: Backup
metadata:
  name: pg-cluster-pg-basebackup
  namespace: demo
spec:
  backupMethod: pg-basebackup
  backupPolicyName: pg-cluster-postgresql-backup-policy
  # Determines whether the backup contents stored in the backup repository should be deleted
  # when the backup custom resource(CR) is deleted. Supported values are `Retain` and `Delete`.
  # - `Retain` means that the backup content and its physical snapshot on backup repository are kept.
  # - `Delete` means that the backup content and its physical snapshot on backup repository are deleted.
  deletionPolicy: Delete

2. Monitor Backup and Verify Completion

Track progress until status shows "Completed":

kubectl get backup pg-cluster-pg-basebackup  -n demo -w

Example Output:

NAME                       POLICY                                METHOD          REPO            STATUS      TOTAL-SIZE   DURATION   DELETION-POLICY   CREATION-TIME          COMPLETION-TIME        EXPIRATION-TIME
pg-cluster-pg-basebackup   pg-cluster-postgresql-backup-policy   pg-basebackup   <BACKUP_REPO>   Completed   4722262      10s        Delete            2025-05-16T02:53:45Z   2025-05-16T02:53:55Z

3. Validate Backup

Confirm successful completion by checking:

• Backup status shows "Completed"
• Backup size matches expectations
• Check files in the BackupRepo

The Backup resource records details including:

• Storage path
• Time range
• Backup file size

Backup via OpsRequest API

1. Create On-Demand Backup

Execute a backup using the OpsRequest API with the 'pg-basebackup' method:

apiVersion: operations.kubeblocks.io/v1alpha1
kind: OpsRequest
metadata:
  name: pg-cluster-backup
  namespace: demo
spec:
  clusterName: pg-cluster
  force: false
  backup:
    backupPolicyName: pg-cluster-postgresql-backup-policy
    backupMethod: pg-basebackup
    deletionPolicy: Delete
    retentionPeriod: 1mo
  type: Backup

2. Monitor Backup Progress

1. Monitor Operation Status

Track backup progress in real-time:

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

Expected Output:

NAME                TYPE     CLUSTER      STATUS    PROGRESS   AGE
pg-cluster-backup   Backup   pg-cluster   Succeed   -/-        35s

• A STATUS of 'Succeed' indicates the backup operation completed successfully.

2. Verify Completion

Check the final backup status:

kubectl get backup -n demo -l operations.kubeblocks.io/ops-name=pg-cluster-backup

Example Output:

NAME                                    POLICY                                METHOD          REPO           STATUS      TOTAL-SIZE   DURATION   DELETION-POLICY   CREATION-TIME          COMPLETION-TIME        EXPIRATION-TIME
backup-demo-pg-cluster-20250516025810   pg-cluster-postgresql-backup-policy   pg-basebackup   <BACKUP_REPO>  Completed   4725590      10s        Delete            2025-05-16T02:58:10Z   2025-05-16T02:58:20Z   2025-06-15T02:58:20Z

• The backup status should show 'Completed'.

3. Validate Backup

Confirm successful completion by checking:

• Backup status shows "Completed"
• Backup size matches expectations
• Files in the BackupRepo

The Backup resource records details including:

• Storage path
• Time range
• Other metadata

Troubleshooting

When encountering backup issues, such as Backup status is Failed or stucks in Runningfor quite a long time, follow these steps to diagnose and resolve the problem:

1. Inspect the Backup resource for any error events or status updates:

kubectl describe backup <BACKUP_NAME> -n demo

2. Verify the backup job status and examine its logs:

kubectl -n demo get job -l app.kubernetes.io/instance=pg-cluster,app.kubernetes.io/managed-by=kubeblocks-dataprotection

And check pod logs:

kubectl -n demo logs <POD_NAME>

3. Review KubeBlocks controller logs for detailed error information:

kubectl -n kb-system logs deploy/kubeblocks -f

Summary

This guide covered:

1. Deploying a replication PostgreSQL cluster
2. Creating full backups using:
   • Direct Backup API
   • Managed OpsRequest API
3. Monitoring and validating backups

Your PostgreSQL data is now securely backed up and ready for restoration when needed.