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

BackupPolicy

BackupPolicy defines a list of backup methods and their configurations. KubeBlocks automatically generates a BackupPolicy for each database cluster if it supports backup (BackupPolicyTemplate is defined).

kubectl get backuppolicytemplate -n demo -l app.kubernetes.io/name=postgresql

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[] | .actionSetName + ", " + .name'

Example Output:

• ActionSetName refers to the name of the ActionSet object that defines the backup and restore actions. If ActionSetName is null, it means the backup method does not require an ActionSet
• Method Name is simply a name of the backup method given by users or defined in the BackupPolicyTemplate. It will be referenced by the BackupSchedule resource.

kubectl get actionset postgresql-wal-g  -oyaml  # where postgresql-basebackup is the ActionSetName

List of Backup methods

KubeBlocks PostgreSQL supports these backup methods:

BackupSchedule

BackupSchedule defines a schedule for backups. It references the BackupPolicy resource and the BackupMethod name.

View the BackupSchedule resource pg-cluster-postgresql-backup-schedule:

kubectl get backupschedule pg-cluster-postgresql-backup-schedule -n demo -oyaml | yq '.spec.schedules[] | .backupMethod + "," + .enabled'

Example Output:

By default, all backup methods are disabled. You can enable it by setting enabled to true on demand. As introduced previously, there are two FULL backup methods: pg-basebackup and wal-g. As wal-g cannot be enabled alone, we use pg-basebackup in this guide.

Step 1. Create On-Demand Backup (using pg-basebackup)

Backup via Backup API

Option 1. Using Backup API

Apply this manifest to create a backup:

apiVersion: dataprotection.kubeblocks.io/v1alpha1
kind: Backup
metadata:
  name: pg-cluster-pg-basebackup2
  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

Option 2. Using OpsRequest API

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

Step 2. Monitor Backup and Verify Completion

You can track the Backup 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

Step 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 in .status including:

• Storage path
• Time range
• Backup file size

Troubleshooting

When encountering backup issues, such as Backup status is Failed or stuck 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: KubeBlocks runs a Job to create a full backup. If the backup task gets stuck, you can track the Job progress:

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>

This job will be deleted when the backup completes.

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.