HOWTO: Provision PostgreSQL HA with pgBackRest and Patroni¶

Purpose: Deploy a PostgreSQL HA cluster (primary + replica + pgBackRest repo) through the HybridOps platform module with validated, structured run records.

Difficulty: Advanced

Track: Platform Services

Overview¶

PostgreSQL HA in HybridOps is a first-class, module-managed configuration: not a manual cluster assembly. This HOWTO walks through the full deployment from module inputs to a validated, replicated, backup-enabled cluster. It is the foundational step for the DR rehearsal workflows covered in Track 06.

1. Module Overview¶

Module ID: platform/onprem/postgresql-ha@v1.
Architecture: primary, replica(s), pgBackRest repository node.
Patroni as the HA orchestrator and DCS backend options.

2. Prerequisites¶

VMs provisioned in the target VLAN with static IPs from IPAM.
DCS backend reachable (etcd, Consul, or Kubernetes API).
SSH access from the control node.

3. Module Inputs¶

Node definitions: primary IP, replica IPs, pgBackRest repo IP.
PostgreSQL version and data directory path.
Replication slot configuration.
pgBackRest stanza name and repository type (POSIX or S3).
Patroni DCS backend endpoint.

4. Running the Module¶

Preflight check walkthrough.
Module execution and step-by-step output.
Expected run duration and what each phase does.

5. Validation¶

Patroni cluster status: patronictl -c /etc/patroni/config.yml list.
Replication lag check.
pgBackRest stanza and baseline backup verification.
Run record review: all steps ok, supporting records present.

6. Common Issues¶

DCS connectivity failures during bootstrap.
Replication slot conflicts on re-run.
pgBackRest repository permission errors.

References¶

License: MIT-0 for code, CC-BY-4.0 for documentation unless otherwise stated.