diff options
Diffstat (limited to 'doc/administration/geo/setup/database.md')
| -rw-r--r-- | doc/administration/geo/setup/database.md | 75 |
1 files changed, 75 insertions, 0 deletions
diff --git a/doc/administration/geo/setup/database.md b/doc/administration/geo/setup/database.md index 09b9c71aeb7..24e55d26997 100644 --- a/doc/administration/geo/setup/database.md +++ b/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). |