setup_patroni

The setup_patroni role configures and starts Patroni for high availability Postgres cluster management. The role generates the Patroni configuration file with etcd connection details 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 Patroni REST API communication.
• 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.
• Apply a patronictl restart to clear any "Pending Restart" flag.

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.
• 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.

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.
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.

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.