From 42179d8312c3a24bdb3ef02892c5783508f632b5 Mon Sep 17 00:00:00 2001 From: Anastasia Alexadrova Date: Wed, 19 Aug 2026 16:21:07 +0200 Subject: [PATCH 1/4] PG-1529 Fixed Patroni config file example and troubleshooting advice. This PR incorporates changes suggested in https://github.com/percona/postgresql-docs/pull/779 --- docs/installing.md | 2 +- docs/solutions/ha-patroni.md | 52 +++++++++++++++++++++--------------- 2 files changed, 32 insertions(+), 22 deletions(-) diff --git a/docs/installing.md b/docs/installing.md index c1e0060df..94afc80f2 100644 --- a/docs/installing.md +++ b/docs/installing.md @@ -40,7 +40,7 @@ Choose the installation method that best fits your environment: === ":octicons-download-16: Tar download (not recommended)" - If installing the package (the **recommended** method for a safe, secure, and reliable setup) is not an option, refer to the link below for step-by-step instructions on installing from tarballs using the provided download links. + Installing the package is the **recommended** method for a safe, secure, and reliable setup. If using this method is not an option, refer to the link below for step-by-step instructions on installing from tarballs using the provided download links. In this scenario, you must ensure that all dependencies are met. Failure to do so may result in errors or crashes. diff --git a/docs/solutions/ha-patroni.md b/docs/solutions/ha-patroni.md index 8b75c4f21..8ff353009 100644 --- a/docs/solutions/ha-patroni.md +++ b/docs/solutions/ha-patroni.md @@ -183,14 +183,14 @@ bootstrap: archive_mode: "on" archive_timeout: 600s archive_command: "cp -f %p /home/postgres/archived/%f" - - pg_hba: # Add following lines to pg_hba.conf after running 'initdb' - - host replication replicator 127.0.0.1/32 trust - - host replication replicator 0.0.0.0/0 md5 - - host all all 0.0.0.0/0 md5 - - host all all ::0/0 md5 - recovery_conf: - restore_command: cp /home/postgres/archived/%f %p + pg_hba: + - local all all peer + - host replication replicator 127.0.0.1/32 trust + - host replication replicator 10.0.0.0/8 scram-sha-256 + - host all all 0.0.0.0/0 scram-sha-256 + - host all all ::0/0 scram-sha-256 + recovery_conf: + restore_command: cp /home/postgres/archived/%f %p # some desired options for 'initdb' initdb: # Note: It needs to be a list (some options need values, others are switches) @@ -238,7 +238,9 @@ tags: The first section provides the details of the node and its connection ports. After that, we have the `etcd` service and its port details. - Following these, there is a `bootstrap` section that contains the PostgreSQL configurations and the steps to run once + The `bootstrap.dcs` section stores cluster-wide settings in etcd. The `pg_hba` and `recovery_conf` entries live under `bootstrap.dcs.postgresql` so Patroni can manage `pg_hba.conf` and recovery settings consistently across all nodes. Authentication uses `scram-sha-256` instead of `md5`. The sample `restore_command` pairs with `archive_mode` and `archive_command` for WAL archiving. Additional database users can be created at any time with standard SQL commands; they are not defined in this file. + + The `postgresql.watchdog` section enables the Linux watchdog for STONITH/fencing when a node hangs, which helps prevent split-brain scenarios. ### Systemd configuration @@ -346,25 +348,33 @@ Now it's time to start Patroni. You need the following commands on all nodes but ### Troubleshooting Patroni startup - A common error is Patroni complaining about the lack of proper entries in the `pg_hba.conf` file. If you see such errors, you must manually add or fix the entries in that file and then restart the service. +A common error is Patroni complaining about the lack of proper entries in the `pg_hba.conf` file. -An example of such an error is `No pg_hba.conf entry for replication connection from host to , user replicator, no encryption`. This means that Patroni cannot connect to the node you're adding to the cluster. To resolve this issue, add the IP addresses of the nodes to the `pg_hba:` section of the Patroni configuration file. +An example of such an error is `No pg_hba.conf entry for replication connection from host to , user replicator, no encryption`. This means that Patroni cannot connect to the node you're adding to the cluster. To resolve this issue, add the IP addresses of the nodes to the `pg_hba` section under `bootstrap.dcs.postgresql` in the Patroni configuration file. Adjust the network CIDR to match your deployment; the sample below uses `10.0.0.0/8` for the lab network: ``` -pg_hba: # Add following lines to pg_hba.conf after running 'initdb' -- host replication replicator 127.0.0.1/32 trust -- host replication replicator 0.0.0.0/0 md5 -- host replication replicator 10.0.100.2/32 trust -- host replication replicator 10.0.100.3/32 trust -- host all all 0.0.0.0/0 md5 -- host all all ::0/0 md5 -recovery_conf: +postgresql: + pg_hba: + - local all all peer + - host replication replicator 127.0.0.1/32 trust + - host replication replicator 10.0.0.0/8 scram-sha-256 + - host replication replicator 10.0.100.2/32 scram-sha-256 + - host replication replicator 10.0.100.3/32 scram-sha-256 + - host all all 0.0.0.0/0 scram-sha-256 + - host all all ::0/0 scram-sha-256 + recovery_conf: restore_command: cp /home/postgres/archived/%f %p ``` -For production use, we recommend adding nodes individually as the more secure way. However, if your network is secure and you trust it, you can add the whole network these nodes belong to as the trusted one to bypass passwords use during authentication. Then all nodes from this network can connect to Patroni cluster. +For production use, we recommend adding nodes individually with specific `/32` entries as the more secure way. However, if your network is secure and you trust it, you can add the whole network these nodes belong to (for example, `10.0.0.0/8`) so all nodes from this network can connect to the Patroni cluster. + +If the cluster is **already running**, changing `patroni.yml` alone does not update `pg_hba.conf`. Update the DCS configuration instead: + +```{.bash data-prompt="$"} +$ sudo patronictl -c /etc/patroni/patroni.yml edit-config +``` -Changing the `patroni.yml` file and restarting the service will not have any effect here because the bootstrap section specifies the configuration to apply when PostgreSQL is first started in the node. It will not repeat the process even if the Patroni configuration file is modified and the service is restarted. +Add or fix the `pg_hba` entries in the editor, save, and Patroni applies the changes across the cluster. For a **new cluster** that has not been bootstrapped yet, fix `patroni.yml` before starting Patroni on the first node. ## Next steps From fef8ed21cff0407d7ca35be9c449688d52d762a4 Mon Sep 17 00:00:00 2001 From: Anastasia Alexandrova Date: Wed, 19 Aug 2026 19:33:52 +0200 Subject: [PATCH 2/4] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- docs/solutions/ha-patroni.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/solutions/ha-patroni.md b/docs/solutions/ha-patroni.md index 8ff353009..fa32668fc 100644 --- a/docs/solutions/ha-patroni.md +++ b/docs/solutions/ha-patroni.md @@ -184,11 +184,11 @@ bootstrap: archive_timeout: 600s archive_command: "cp -f %p /home/postgres/archived/%f" pg_hba: - - local all all peer - - host replication replicator 127.0.0.1/32 trust - - host replication replicator 10.0.0.0/8 scram-sha-256 - - host all all 0.0.0.0/0 scram-sha-256 - - host all all ::0/0 scram-sha-256 + - local all all peer + - host replication replicator 127.0.0.1/32 trust + - host replication replicator 10.0.0.0/8 scram-sha-256 + - host all all 0.0.0.0/0 scram-sha-256 + - host all all ::0/0 scram-sha-256 recovery_conf: restore_command: cp /home/postgres/archived/%f %p From 9f794585db4de6cb2d7e610a99b3f0d1cbe8ace5 Mon Sep 17 00:00:00 2001 From: Anastasia Alexandrova Date: Wed, 19 Aug 2026 19:37:15 +0200 Subject: [PATCH 3/4] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- docs/solutions/ha-patroni.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/solutions/ha-patroni.md b/docs/solutions/ha-patroni.md index fa32668fc..9aaf5fb5f 100644 --- a/docs/solutions/ha-patroni.md +++ b/docs/solutions/ha-patroni.md @@ -350,7 +350,7 @@ Now it's time to start Patroni. You need the following commands on all nodes but A common error is Patroni complaining about the lack of proper entries in the `pg_hba.conf` file. -An example of such an error is `No pg_hba.conf entry for replication connection from host to , user replicator, no encryption`. This means that Patroni cannot connect to the node you're adding to the cluster. To resolve this issue, add the IP addresses of the nodes to the `pg_hba` section under `bootstrap.dcs.postgresql` in the Patroni configuration file. Adjust the network CIDR to match your deployment; the sample below uses `10.0.0.0/8` for the lab network: +An example of such an error is `No pg_hba.conf entry for replication connection from host to , user replicator, no encryption`. This means that Patroni cannot connect to the node you're adding to the cluster. To resolve this issue, add the IP addresses of the nodes to the cluster-wide `pg_hba` list under `postgresql` (stored in the DCS). For a **new cluster** that has not been bootstrapped yet, define the same `pg_hba` list under `bootstrap.dcs.postgresql` in `patroni.yml` before starting Patroni on the first node. Adjust the network CIDR to match your deployment; the sample below uses `10.0.0.0/8` for the lab network: ``` postgresql: From 67cc61ac80239f9377ba2cd1e2f8c6411a11aef0 Mon Sep 17 00:00:00 2001 From: Anastasia Alexadrova Date: Wed, 19 Aug 2026 19:38:56 +0200 Subject: [PATCH 4/4] Indentation fix --- docs/solutions/ha-patroni.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/solutions/ha-patroni.md b/docs/solutions/ha-patroni.md index 9aaf5fb5f..b87048a26 100644 --- a/docs/solutions/ha-patroni.md +++ b/docs/solutions/ha-patroni.md @@ -355,13 +355,13 @@ An example of such an error is `No pg_hba.conf entry for replication connection ``` postgresql: pg_hba: - - local all all peer - - host replication replicator 127.0.0.1/32 trust - - host replication replicator 10.0.0.0/8 scram-sha-256 - - host replication replicator 10.0.100.2/32 scram-sha-256 - - host replication replicator 10.0.100.3/32 scram-sha-256 - - host all all 0.0.0.0/0 scram-sha-256 - - host all all ::0/0 scram-sha-256 + - local all all peer + - host replication replicator 127.0.0.1/32 trust + - host replication replicator 10.0.0.0/8 scram-sha-256 + - host replication replicator 10.0.100.2/32 scram-sha-256 + - host replication replicator 10.0.100.3/32 scram-sha-256 + - host all all 0.0.0.0/0 scram-sha-256 + - host all all ::0/0 scram-sha-256 recovery_conf: restore_command: cp /home/postgres/archived/%f %p ```