Merge branch '225326-geo-document-patroni-geo-deployment-docs' into 'master'

Geo: Document Patroni Geo Deployment

See merge request gitlab-org/gitlab!45703

doc/administration/geo/setup/database.md

@@ -474,6 +474,81 @@ high-availability configuration with a cluster of nodes supporting a Geo
 **primary** node and another cluster of nodes supporting a Geo **secondary** node. For more
 information, see [High Availability with Omnibus GitLab](../../postgresql/replication_and_failover.md).
 
+## Patroni support
+
+Support for Patroni is intended to replace `repmgr` as a
+[highly availabile PostgreSQL solution](../../postgresql/replication_and_failover.md) 
+on the primary node, but it can also be used for PostgreSQL HA on a secondary
+node.
+
+Starting with GitLab 13.5, Patroni is available for _experimental_ use with Geo
+primary and secondary nodes. Due to its experimental nature, Patroni support is
+subject to change without notice.
+
+This experimental implementation has the following limitations:
+
+- Whenever a new Leader is elected, the PgBouncer instance must be reconfigured
+  to point to the new Leader.
+- Whenever a new Leader is elected on the primary node, the Standby Leader on
+  the secondary needs to be reconfigured to point to the new Leader.
+- Whenever `gitlab-ctl reconfigure` runs on a Patroni Leader instance, there's a
+  chance the node will be demoted due to the required short-time restart. To
+  avoid this, you can pause auto-failover by running `gitlab-ctl patroni pause`.
+  After a reconfigure, it unpauses on its own.
+
+For instructions about how to set up Patroni on the primary node, see the 
+[PostgreSQL replication and failover with Omnibus GitLab](../../postgresql/replication_and_failover.md#patroni) page.
+
+A production-ready and secure setup requires at least three Patroni instances on
+the primary, and a similar configuration on the secondary nodes. Be sure to use
+password credentials and other database best practices.
+
+Similar to `repmgr`, using Patroni on a secondary node is optional. 
+
+To set up database replication with Patroni on a secondary node, configure a
+_permanent replication slot_ on the primary node's Patroni cluster, and ensure
+password authentication is used.
+
+On Patroni instances for the primary node, add the following to the
+`/etc/gitlab/gitlab.rb` file:
+
+```ruby
+# You need one entry for each secondary, with a unique name following PostgreSQL slot_name constraints:
+#
+# Configuration syntax will be: 'unique_slotname' => { 'type' => 'physical' },
+# We don't support setting a permanent replication slot for logical replication type 
+patroni['replication_slots'] = {
+    'geo_secondary' => { 'type' => 'physical' }
+}
+
+postgresql['md5_auth_cidr_addresses'] = [
+  'PATRONI_PRIMARY1_IP/32', 'PATRONI_PRIMARY2_IP/32', 'PATRONI_PRIMARY3_IP/32', 'PATRONI_PRIMARY_PGBOUNCER/32',
+  'PATRONI_SECONDARY1_IP/32', 'PATRONI_SECONDARY2_IP/32', 'PATRONI_SECONDARY3_IP/32' # we list all secondary instances as they can all become a Standby Leader
+  # any other instance that needs access to the database as per documentation 
+]
+
+postgresql['pgbouncer_user_password'] = 'PGBOUNCER_PASSWORD_HASH'
+postgresql['sql_replication_password'] = 'POSTGRESQL_REPLICATION_PASSWORD_HASH'
+postgresql['sql_user_password'] = 'POSTGRESQL_PASSWORD_HASH'
+```
+
+On Patroni instances for the secondary node, add the following to the
+`/etc/gitlab/gitlab.rb` file:
+
+```ruby
+postgresql['md5_auth_cidr_addresses'] = [
+  'PATRONI_SECONDARY1_IP/32', 'PATRONI_SECONDARY2_IP/32', 'PATRONI_SECONDARY3_IP/32', 'PATRONI_SECONDARY_PGBOUNCER/32',
+  # any other instance that needs access to the database as per documentation 
+]
+
+patroni['enable'] = true
+patroni['standby_cluster']['enable'] = true
+patroni['standby_cluster']['host'] = 'PATRONI_PRIMARY_LEADER_IP' # this needs to be changed anytime the primary Leader changes
+patroni['standby_cluster']['port'] = 5432
+patroni['standby_cluster']['primary_slot_name'] = 'geo_secondary' # or the unique replication slot name you setup before
+patroni['replication_password'] = 'PLAIN_TEXT_POSTGRESQL_REPLICATION_PASSWORD'
+```
+
 ## Troubleshooting
 
 Read the [troubleshooting document](../replication/troubleshooting.md).