Learn pgBackRest - Integration: Docker, K8s & Cloud

#Introduction

More and more PostgreSQL databases run inside containers and Kubernetes — and backups can't be left behind. In episode 20 we bring pgBackRest into the modern world: the sidecar pattern on Kubernetes via the CloudNativePG operator, a Docker image with a mounted config, and cloud object storage integration (S3/GCS/Azure Blob) with cloud-native credential management (IAM role vs static key).

The principles haven't changed from the previous 19 episodes: stanza, check, backup, restore, retention. What changes is how the binary is run and how credentials are provided. Understand both, and pgBackRest in a container is just as reliable as on bare metal.

#pgBackRest in Docker

#An Image with a Config Mount

The simplest approach: run pgBackRest in a container whose image already has the binary, then mount the config and repository:

FROM debian:bookworm-slim
RUN apt-get update \
 && apt-get install -y pgbackrest postgresql-client \
 && rm -rf /var/lib/apt/lists/*
ENTRYPOINT ["pgbackrest"]

Run it with volumes:

docker run --rm \
  -v /etc/pgbackrest.conf:/etc/pgbackrest.conf:ro \
  -v /var/lib/pgbackrest:/var/lib/pgbackrest \
  pgbackrest:2.59.0 --stanza=main backup --type=full

The key to success is the volumes: the config is mounted read-only, the repository is persisted. The container itself can be destroyed at any time — the backup data is safe on the volume.

#CloudNativePG: The pgBackRest Sidecar on Kubernetes

#Why the Operator Manages Backups

The CloudNativePG (CNPG) operator makes pgBackRest an inseparable part of a PostgreSQL cluster on Kubernetes: it creates the stanza, schedules backups, manages WAL archiving, and handles restore — all through Kubernetes resources. You no longer write pgbackrest backup manually; you declare the desired state, the operator does the work.

#Declaring Backups

apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: aplikasi-db
spec:
  instances: 3
  storage:
    size: 100Gi
  backup:
    barmanObjectStore:
      destinationPath: s3://cnpg-backup-prod
      s3Credentials:
        accessKeyId:
          name: s3-credentials
          key: accessKeyId
        secretAccessKey:
          name: s3-credentials
          key: secretAccessKey
    retentionPolicy: "30d"
  walStorage:
    size: 20Gi

• destinationPath — the object storage URL (S3, GCS, Azure).
• s3Credentials — a reference to a Kubernetes Secret containing the credentials.
• retentionPolicy — the retention policy as a duration (for example 30d).

Every cluster declared like this automatically gets: a created stanza, archived WAL, scheduled full backups, and restore available via the Backup resource.

#Restore via the Operator

Restore is done by declaring a Backup resource — the operator runs pgBackRest behind the scenes:

apiVersion: postgresql.cnpg.io/v1
kind: Backup
metadata:
  name: restore-20260813
spec:
  cluster:
    name: aplikasi-db

An important point for you: everything learned in these 19 episodes (stanza, WAL, retention, PITR) remains the same concept in CNPG — the operator only automates the execution. Knowing pgBackRest directly makes debugging CNPG much easier.

#Cloud: S3, GCS, and Azure Blob

#S3-Compatible

Already covered in episode 12: repo1-type=s3 supports AWS S3 and all S3-compatible storage. For GCS and Azure Blob, pgBackRest has its own types:

[global]
# GCS
repo1-type = gcs
repo1-gcs-bucket = db-backup-gcs
repo1-gcs-key = /etc/pgbackrest/gcs-key.json
repo1-gcs-endpoint = storage.googleapis.com

[global]
# Azure Blob
repo1-type = azure
repo1-azure-account = backupaccount
repo1-azure-container = db-backup
repo1-azure-key = <storage-account-key>

All three use the same concepts: endpoint, bucket/container, and credentials. Once the config is correct, all commands (stanza-create, check, backup) are identical.

#IAM Role vs Static Key

Two ways to provide cloud credentials — and both have trade-offs:

For cloud instances, an IAM role (AWS), Workload Identity (GCP), or Managed Identity (Azure) is the best practice: credentials are never written to the config, and permissions can be narrowed (only access to a specific bucket). pgBackRest supports repo1-s3-role for getting credentials from a role:

[global]
repo1-type = s3
repo1-s3-bucket = db-backup-prod
repo1-s3-endpoint = s3.ap-southeast-1.amazonaws.com
repo1-s3-region = ap-southeast-1
repo1-s3-role = arn:aws:iam::123456789012:role/pgbackrest-backup-role

#Building a Platform, Not a Server

After episode 20, your pgBackRest can live in three worlds at once: bare metal (episodes 3-19), Docker containers, and Kubernetes via CNPG — with the same backup destination (S3/GCS/Azure). This isn't three different systems; it's one system with three homes. The same skills, the same configuration, the same debugging.

#Conclusion

Key takeaways:

• pgBackRest in Docker = image + config mount + repository volume.
• CloudNativePG automates stanza/backup/restore via Kubernetes resources — the concepts are the same.
• S3/GCS/Azure Blob each have their own repository type; the commands are identical.
• IAM role/Workload Identity for cloud production; static keys for labs and on-prem storage.
• One pgBackRest skill applies in every home: bare metal, containers, and cloud.

In the next episode we'll look ahead: roadmap & community — the development direction of pgBackRest focused on reliability and object storage, the complete user guide documentation, and how to join the community on GitHub, Slack, and the mailing list. The tool you use isn't a frozen artifact — it lives together with its community!