Configure pgBackRest backups for a PostgresCluster

PGO integrates pgBackRest as its backup and WAL archiving engine. pgBackRest handles full, incremental, and differential backup types; continuous WAL archiving for point-in-time recovery; and restore operations including bootstrapping new clusters from existing backups. Up to four repositories (repo1–repo4) can be configured simultaneously, letting you combine storage backends for redundancy.

Backup types

pgBackRest supports three backup types. All three are available through the schedules field of each repository.

Type	Flag	Description
Full	`full`	A complete copy of all data files. All other backup types depend on a prior full backup.
Differential	`diff`	All files changed since the last full backup. Smaller than full; requires the last full to restore.
Incremental	`incr`	All files changed since the last backup of any type. The smallest backup; requires the full chain to restore.

Backup to a local PVC volume

Local volume repositories are the simplest option. The operator deploys a dedicated repository host pod that manages the backup storage.

apiVersion: postgres-operator.crunchydata.com/v1beta1
kind: PostgresCluster
metadata:
  name: hippo
spec:
  postgresVersion: 16
  instances:
    - name: instance1
      dataVolumeClaimSpec:
        accessModes:
          - "ReadWriteOnce"
        resources:
          requests:
            storage: 10Gi
  backups:
    pgbackrest:
      repos:
        - name: repo1
          volume:
            volumeClaimSpec:
              accessModes:
                - "ReadWriteOnce"
              resources:
                requests:
                  storage: 20Gi

Size the backup PVC generously. A good starting point is 2× the data volume for a cluster that runs weekly full backups and daily incrementals.

Backup to object storage

S3
GCS
Azure Blob Storage

Create a Kubernetes Secret with your AWS credentials, then reference the S3 bucket, endpoint, and region in the repo spec.

kubectl create secret generic hippo-s3-creds \
  --from-literal=aws-s3-key=AKIAIOSFODNN7EXAMPLE \
  --from-literal=aws-s3-key-secret=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

spec:
  backups:
    pgbackrest:
      configuration:
        - secret:
            name: hippo-s3-creds
      global:
        repo1-s3-key: aws-s3-key
        repo1-s3-key-secret: aws-s3-key-secret
      repos:
        - name: repo1
          s3:
            bucket: my-postgres-backups
            endpoint: s3.us-east-1.amazonaws.com
            region: us-east-1

For S3-compatible endpoints (MinIO, Ceph, Backblaze B2), set endpoint to your compatible storage URL and add repo1-s3-uri-style: path in global if path-style URLs are required.

Mount your GCS service account JSON key as a projected Secret, then specify the bucket name.

kubectl create secret generic hippo-gcs-creds \
  --from-file=gcs-key.json=/path/to/service-account-key.json

spec:
  backups:
    pgbackrest:
      configuration:
        - secret:
            name: hippo-gcs-creds
      global:
        repo1-gcs-key: /etc/pgbackrest/conf.d/gcs-key.json
      repos:
        - name: repo1
          gcs:
            bucket: my-postgres-gcs-backups

Provide the Azure storage account name and key as a Secret, then reference the container name.

kubectl create secret generic hippo-azure-creds \
  --from-literal=azure-account=mystorageaccount \
  --from-literal=azure-key=BASE64ENCODEDKEYHERE==

spec:
  backups:
    pgbackrest:
      configuration:
        - secret:
            name: hippo-azure-creds
      global:
        repo1-azure-account: azure-account
        repo1-azure-key: azure-key
      repos:
        - name: repo1
          azure:
            container: my-postgres-backups

Multiple repositories

Configuring multiple repos provides redundancy and lets you combine storage backends. For example, keep a fast local volume for quick restores and an S3 repo for off-site retention.

spec:
  backups:
    pgbackrest:
      configuration:
        - secret:
            name: hippo-s3-creds
      global:
        repo2-s3-key: aws-s3-key
        repo2-s3-key-secret: aws-s3-key-secret
      repos:
        - name: repo1
          volume:
            volumeClaimSpec:
              accessModes:
                - "ReadWriteOnce"
              resources:
                requests:
                  storage: 20Gi
        - name: repo2
          s3:
            bucket: my-postgres-backups
            endpoint: s3.us-east-1.amazonaws.com
            region: us-east-1

At minimum, keep one off-site repository. A local-only backup cannot protect against storage volume loss or cluster-wide disasters.

Scheduled backups

Set a cron schedule on each repo to automate full, differential, and incremental backups. Schedules follow standard Kubernetes cron syntax.

spec:
  backups:
    pgbackrest:
      repos:
        - name: repo1
          volume:
            volumeClaimSpec:
              accessModes:
                - "ReadWriteOnce"
              resources:
                requests:
                  storage: 20Gi
          schedules:
            full: "0 1 * * 0"          # Every Sunday at 01:00 UTC
            differential: "0 1 * * 1-6" # Monday–Saturday at 01:00 UTC
            incremental: "0 */4 * * *"  # Every 4 hours

The operator creates a Kubernetes CronJob for each schedule. Inspect them with:

kubectl get cronjobs -l postgres-operator.crunchydata.com/cluster=hippo

Trigger a manual backup

Annotate the PostgresCluster with postgres-operator.crunchydata.com/pgbackrest-backup and specify the target repo in spec.backups.pgbackrest.manual.

Add the manual backup spec

spec:
  backups:
    pgbackrest:
      manual:
        repoName: repo1
        options:
          - --type=full

Annotate to trigger the backup

The annotation value must be unique each time you want to trigger a new backup. Use a timestamp or a meaningful label.

kubectl annotate postgrescluster hippo \
  postgres-operator.crunchydata.com/pgbackrest-backup="$(date +%Y%m%d-%H%M%S)"

Monitor backup progress

kubectl get jobs \
  -l postgres-operator.crunchydata.com/pgbackrest=manual \
  -l postgres-operator.crunchydata.com/cluster=hippo

kubectl logs -l postgres-operator.crunchydata.com/pgbackrest=manual \
  -l postgres-operator.crunchydata.com/cluster=hippo --tail=50

Global pgBackRest configuration

spec.backups.pgbackrest.global maps directly to pgBackRest’s [global] configuration section. Use it to set retention policies, compression, and process counts.

spec:
  backups:
    pgbackrest:
      global:
        # Keep 4 full backups in repo1
        repo1-retention-full: "4"
        repo1-retention-full-type: count
        # Keep 14 days of differential backups
        repo1-retention-diff: "14"
        # Use lz4 compression for faster backup/restore
        repo1-compress-type: lz4
        # Use 2 parallel processes for backup and restore
        process-max: "2"

Resource limits for backup jobs

Set CPU and memory limits on backup job pods through spec.backups.pgbackrest.jobs.resources. This prevents backup jobs from starving the primary during heavy backup windows.

spec:
  backups:
    pgbackrest:
      jobs:
        resources:
          requests:
            cpu: "100m"
            memory: "128Mi"
          limits:
            cpu: "500m"
            memory: "512Mi"

Check backup status

# View pgBackRest status in the cluster's status subresource
kubectl get postgrescluster hippo -o jsonpath='{.status.pgbackrest}' \
  | python3 -m json.tool

# List all CronJobs for scheduled backups
kubectl get cronjobs -l postgres-operator.crunchydata.com/cluster=hippo

# View completed backup jobs
kubectl get jobs -l postgres-operator.crunchydata.com/cluster=hippo

Disaster recovery

Restore from a pgBackRest backup and perform point-in-time recovery.

High availability

Configure Patroni-managed failover alongside your backup strategy.

Create a cluster

Build the base PostgresCluster spec with instances and storage.

Custom Resource Reference

Full field reference for spec.backups.pgbackrest.

Get Started

Installation

Core Operations

Day-Two Operations

Security

Configure pgBackRest backups for a PostgresCluster

Backup types

Backup to a local PVC volume

Backup to object storage

Multiple repositories

Scheduled backups

Trigger a manual backup

Global pgBackRest configuration

Resource limits for backup jobs

Check backup status

Disaster recovery

High availability

Create a cluster

Custom Resource Reference

​Backup types

​Backup to a local PVC volume

​Backup to object storage

​Multiple repositories

​Scheduled backups

​Trigger a manual backup

​Global pgBackRest configuration

​Resource limits for backup jobs

​Check backup status

Disaster recovery

High availability

Create a cluster

Custom Resource Reference

Backup types

Backup to a local PVC volume

Backup to object storage

Multiple repositories

Scheduled backups

Trigger a manual backup

Global pgBackRest configuration

Resource limits for backup jobs

Check backup status