Role Reference

This page describes each role in the pgEdge Ansible Collection and provides links to detailed documentation for each role.

Role Execution Order

Roles must be applied in a specific order to satisfy dependencies. The following list shows the correct execution sequence:

1. init_server - Prepares all servers in the cluster.
2. install_repos - Installs the pgEdge and PGDG package repositories.
3. install_pgedge - Installs pgEdge packages on pgEdge nodes.
4. install_etcd - Installs etcd on pgEdge nodes (HA only).
5. install_patroni - Installs Patroni on pgEdge nodes (HA only).
6. install_backrest - Installs PgBackRest on backup-capable nodes.
7. install_pgbouncer - Installs pgBouncer on pgEdge nodes (pooled clusters only).
8. setup_backrest - Writes the PgBackRest configuration.
9. setup_postgres - Initializes PostgreSQL on pgEdge nodes.
10. setup_etcd - Configures and starts etcd (HA only).
11. setup_patroni - Configures Patroni and starts the HA cluster (HA only).
12. setup_pgbouncer - Configures and starts pgBouncer on pooled nodes.
13. setup_haproxy - Configures HAProxy on haproxy nodes (HA only).
14. setup_pgedge - Creates Spock nodes and establishes subscriptions.
15. finalize_backrest - Initializes the backup repository and schedules backups.

setup_backrest comes before setup_postgres, and therefore before setup_patroni, for two reasons. An HA cluster gets its archive_command from the Patroni configuration, so Postgres starts archiving the moment Patroni starts it, and a pgbackrest.conf written later leaves a window in which every archive attempt fails. And setup_postgres asks the repository whether it already holds a cluster before it initializes a data directory, which it can only do once pgbackrest.conf names the repository. Nothing setup_backrest does touches Postgres, so it can sit that early.

That question matters when the only thing that survived an outage is the backup repository. Deploying onto replacement hardware with the original inventory would otherwise build an empty cluster whose system identifier does not match the stanza — one that can never archive to its own repository, while appearing healthy. setup_postgres refuses instead and points at the recovery playbook. The check is skipped during a recovery, where an empty data directory beside a full repository is exactly what was intended.

finalize_backrest is last because everything it does needs a cluster that is up and wired together. It takes a full backup only when the repository holds no backup that can restore the cluster running now, so re-running a playbook against a cluster whose repository already holds such backups adds nothing to it — which matters, because the default retention would otherwise expire the recovery point the repository already had.

The two pgBouncer roles are the only optional pair in the sequence. Pooling is opt-in per cluster, so both are gated on pgbouncer_enabled; a cluster that does not pool omits them and is otherwise unchanged. See Pooling Configuration.

wipe_cluster is not part of this sequence: it tears a cluster down so the sequence can run again. A recovery runs the same sequence with recover_postgres in place of setup_postgres and stops short of finalize_backrest until the result is committed. It also sets up the backup servers before the pgEdge nodes, since the restore reads from them, and runs setup_pgedge with pgedge_seed_zone set to the restored zone. See Recovering a Cluster from Backup.

Role Categories

The roles in this collection fall into five categories.

Configuration Foundation

Server Preparation

Software Installation

Service Configuration

Recovery