Setting Up a PostgreSQL Cluster with Scheduled Backups in KubeBlocks

This guide demonstrates how to deploy a PostgreSQL cluster using KubeBlocks and configure scheduled backups with retention in an S3 repository.

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.

Prerequisites for Backup

1. Backup Repository Configured:

   • Configured BackupRepo
   • Network connectivity between cluster and repo, BackupRepo status is Ready

2. Cluster is Running:

   • Cluster must be in Running state
   • No ongoing operations (scaling, upgrades etc.)

Configure Scheduled Backups (using pg-basebackup and archive-wal)

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

KubeBlocks automatically creates a BackupSchedule resource when the cluster is created. Follow these steps to enable and configure scheduled backups:

View default backup schedule configuration:

kubectl get backupschedule pg-cluster-postgresql-backup-schedule  -n demo -oyaml

Example Output:

apiVersion: dataprotection.kubeblocks.io/v1alpha1
kind: BackupSchedule
spec:
  backupPolicyName: pg-cluster-postgresql-backup-policy
  schedules:
  - backupMethod: pg-basebackup
    # ┌───────────── minute (0-59)
    # │ ┌───────────── hour (0-23)
    # │ │ ┌───────────── day of month (1-31)
    # │ │ │ ┌───────────── month (1-12)
    # │ │ │ │ ┌───────────── day of week (0-6) (Sunday=0)
    # │ │ │ │ │
    # 0 18 * * *
    # schedule this job every day at 6:00 PM (18:00).
    cronExpression: 0 18 * * * # update the cronExpression to your need
    enabled: false # set to `true` to schedule base backup periodically
    retentionPeriod: 7d # set the retention period to your need

To check if an backup method is enabled, you can run the following command:

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.

There are two ways to enable a backup method and we will introduce them in the following sections.

Option 1. Edit the BackupSchedule resource

Enable and customize the backup schedule:

kubectl edit backupschedule pg-cluster-postgresql-backup-schedule -n demo

Update these key parameters:

• enabled: Set to true to activate scheduled backups
• cronExpression: Configure backup frequency using cron syntax
• retentionPeriod: Set how long to keep backups (e.g., 7d, 1mo)

Example configuration for daily backups at 6PM UTC with 7-day retention:

schedules:
- backupMethod: pg-basebackup
  enabled: true
  cronExpression: "0 18 * * *"
  retentionPeriod: 7d

Option 2. Edit the Cluster resource with backup method

Or you can patch an existing cluster to enable scheduled backup:

kubectl patch cluster pg-cluster -n demo --type='merge' -p='
{
  "spec": {
    "backup": {
      "retentionPeriod": "7d",
      "method": "pg-basebackup",
      "enabled": true,
      "incrementalBackupEnabled": false,
      "pitrEnabled": false,
      "cronExpression": "0 18 * * *",
      "repoName": "s3-repo"
    }
  }
}'

Verify the configuration

View schedule configuration

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

Example Output:

Only pg-basebackup is enabled.

Check CronJob

KubeBlocks create a CronJob to schedule full backups. You can check the CronJob status:

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

Example Output:

NAME                                           SCHEDULE     TIMEZONE   SUSPEND   ACTIVE   LAST SCHEDULE   AGE
b387c27b-pg-cluster-postgresql-pg-basebackup   0 18 * * *   UTC        False     0        12h             3d5h

If there is no CronJob, please check the BackupSchedule resource the full backup method pg-basebackup is enabled.

Monitoring and Managing Backups

After enabling scheduled backups, monitor their execution and manage backup retention:

1. View all backups:

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

2. Inspect backup details:

kubectl describe backup <backup-name> -n demo

3. Verify backup artifacts:

• Status should show "Completed"
• Check backup size matches expectations
• Confirm retention period is being applied
• Validate backup files exist in repository

4. Manage backup retention:

• To manually delete old backups:

kubectl delete backup <backup-name> -n demo

• To modify retention period:

kubectl edit backupschedule pg-cluster-postgresql-backup-schedule -n demo

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

This guide demonstrated:

1. Configuration of automated PostgreSQL backups
2. Schedule customization using cron syntax
3. Retention policy management
4. Backup verification procedures

Your PostgreSQL cluster now has:

• Regular automated backups
• Configurable retention policies
• Complete backup history tracking