setup_patroni

The setup_patroni role configures and starts Patroni for high availability Postgres cluster management. The role generates the Patroni configuration file with connection details for the distributed configuration store and Postgres settings, then orchestrates the startup sequence to ensure proper cluster formation.

The role performs the following tasks on inventory hosts:

• Generate TLS certificates for communicating with etcd, when the cluster uses an etcd store.
• Install the replica method that restores from the backup repository, when patroni_replica_from_backup is enabled and a backup repository is configured.
• Generate the patroni.yaml configuration file from a template.
• Disable the native Postgres systemd service so Patroni takes control.
• Start Patroni on the primary node first, then on all replica nodes.
• Wait for the cluster to reach a running state before proceeding.
• Bring the Postgres parameters in the zone's configuration store up to date with the inventory's pg_parameters and the collection's defaults, removing any parameter the configuration no longer names.
• Restart, with patronictl restart, each member that Patroni reports as waiting on a restart: one member at a time, replicas before the leader, and then any replica the leader's restart left waiting, which is what lowering a parameter such as max_worker_processes does. When pg_allow_restart is false, report those members instead.
• Restart the primary once after Patroni first takes it over, whatever pg_allow_restart says, so that a new zone starts with its full configuration.

Role Dependencies

This role requires the following roles for normal operation:

• role_config provides shared configuration variables to the role.
• install_patroni installs Patroni packages and creates the config directory.
• setup_etcd starts the etcd cluster for distributed consensus, and is required only when patroni_dcs.type is etcd or etcd3.
• setup_postgres initializes Postgres instances.

When to Use

Execute this role on all pgedge hosts in high availability configurations after setting up etcd and Postgres, when using the collection to manage etcd directly.

In the following example, the playbook invokes the role after etcd and Postgres setup:

- hosts: pgedge
  collections:
    - pgedge.platform
  roles:
    - setup_postgres
    - setup_etcd
    - setup_patroni

Configuration

This role uses the following parameters from the inventory file:

See the Configuration Reference for descriptions and defaults.

How It Works

The role configures Patroni and orchestrates cluster formation.

Patroni Configuration

The role performs the following steps:

1. Copy the CA certificate from {{ etcd_tls_dir }} and generate a Patroni client key and certificate for communicating with etcd. The role skips this step when patroni_dcs.type names a store other than etcd or etcd3, because an external store supplies its own credentials.
2. Generate the Patroni configuration file. On RHEL systems the file is named patroni.yml; on Debian systems the file is named {{ pg_version }}-{{ cluster_name }}.yml. Both files are stored in /etc/patroni/.
3. Disable the native Postgres systemd service so Patroni has exclusive control of the Postgres lifecycle.
4. Start Patroni on the designated primary node and wait for the cluster primary to become available.
5. Start Patroni on all replica nodes. Patroni rebuilds each replica from the primary using streaming replication.
6. Wait for the cluster to reach a running state (up to 30 retries with a 10-second delay between attempts).
7. Restart Postgres through Patroni to apply settings and clear the "Pending Restart" flag.

Postgres Settings Managed by Patroni

Patroni configures PostgreSQL with the following settings for Spock compatibility:

• WAL level set to logical.
• Shared preload libraries set to pg_stat_statements, snowflake, and spock.
• DDL replication enabled via Spock.
• Spock replication slots excluded from Patroni slot management to prevent conflicts.

Usage Examples

In the following example, the playbook deploys an HA cluster with synchronous replication enabled:

- hosts: pgedge
  collections:
    - pgedge.platform
  vars:
    is_ha_cluster: true
    synchronous_mode: true
    synchronous_mode_strict: true
  roles:
    - setup_patroni

In the following example, the playbook adds custom pg_hba.conf rules through the Patroni configuration:

- hosts: pgedge
  collections:
    - pgedge.platform
  vars:
    is_ha_cluster: true
    custom_hba_rules:
      - contype: hostssl
        users: app_user
        databases: production
        source: 10.0.0.0/8
        method: scram-sha-256
  roles:
    - setup_patroni

Artifacts

This role generates the following files on inventory hosts:

Platform-Specific Behavior

On Debian-based systems, the configuration file is named {{ pg_version }}-{{ cluster_name }}.yml. For example, the default settings produce a file named /etc/patroni/17-demo.yml. On RHEL-based systems, the configuration file is named patroni.yml.

Debian keeps postgresql.conf in /etc/postgresql/<version>/<cluster>, which neither pg_basebackup nor a PgBackRest restore creates, and Patroni cannot start a replica without it. Debian replicas are therefore built with pg_clonecluster, which creates the directory before it clones. With patroni_replica_from_backup enabled, the restore runs first through /usr/local/bin/patroni_pgbackrest_replica, which creates the directory after restoring, and pg_clonecluster is the fallback.

Idempotency

This role has limited idempotency. The role regenerates configuration files, disables the native Postgres service, and restarts Patroni and Postgres on subsequent runs to ensure configuration changes apply.