- Primary node
- Secondary nodes
This document is relevant if you are using a PostgreSQL instance that is not managed by Omnibus. This includes cloud-managed instances like AWS RDS, or manually installed and configured PostgreSQL instances.
SSH into a GitLab primary application server and login as root:
/etc/gitlab/gitlab.rband add a unique ID for your node (arbitrary value):
# The unique identifier for the Geo node. gitlab_rails['geo_node_name'] = '<node_name_here>'
Reconfigure the primary node for the change to take effect:
Execute the command below to define the node as primary node:
This command will use your defined
To set up an external database, you can either:
- Set up streaming replication yourself (for example, in AWS RDS).
- Perform the Omnibus configuration manually as follows.
Given you have a primary node set up on AWS EC2 that uses RDS. You can now just create a read-only replica in a different region and the replication process will be managed by AWS. Make sure you’ve set Network ACL, Subnet, and Security Group according to your needs, so the secondary application node can access the database.
The following instructions detail how to create a read-only replica for common cloud providers:
- Amazon RDS - Creating a Read Replica
- Azure Database for PostgreSQL - Create and manage read replicas in Azure Database for PostgreSQL
Once your read-only replica is set up, you can skip to configure you secondary application node.
configures the primary node’s database to be replicated by making changes to
postgresql.conf. Make the following configuration changes
manually to your external database configuration and ensure that you restart PostgreSQL
afterwards for the changes to take effect:
## ## Geo Primary Role ## - pg_hba.conf ## host all all <trusted primary IP>/32 md5 host replication gitlab_replicator <trusted primary IP>/32 md5 host all all <trusted secondary IP>/32 md5 host replication gitlab_replicator <trusted secondary IP>/32 md5
## ## Geo Primary Role ## - postgresql.conf ## wal_level = hot_standby max_wal_senders = 10 wal_keep_segments = 50 max_replication_slots = 1 # number of secondary instances hot_standby = on
Make the following configuration changes manually to your
of your external replica database and ensure that you restart PostgreSQL afterwards
for the changes to take effect:
## ## Geo Secondary Role ## - pg_hba.conf ## host all all <trusted secondary IP>/32 md5 host replication gitlab_replicator <trusted secondary IP>/32 md5 host all all <trusted primary IP>/24 md5
## ## Geo Secondary Role ## - postgresql.conf ## wal_level = hot_standby max_wal_senders = 10 wal_keep_segments = 10 hot_standby = on
With Omnibus, the
has three main functions:
- Configure the replica database.
- Configure the tracking database.
- Enable the Geo Log Cursor (not covered in this section).
To configure the connection to the external read-replica database and enable Log Cursor:
SSH into a GitLab secondary application server and login as root:
/etc/gitlab/gitlab.rband add the following
## ## Geo Secondary role ## - configure dependent flags automatically to enable Geo ## roles ['geo_secondary_role'] # note this is shared between both databases, # make sure you define the same password in both gitlab_rails['db_password'] = '<your_password_here>' gitlab_rails['db_username'] = 'gitlab' gitlab_rails['db_host'] = '<database_read_replica_host>' # Disable the bundled Omnibus PostgreSQL, since we are # using an external PostgreSQL postgresql['enable'] = false
Save the file and reconfigure GitLab
Secondary nodes use a separate PostgreSQL installation as a tracking
database to keep track of replication status and automatically recover from
potential replication issues. Omnibus automatically configures a tracking database
roles ['geo_secondary_role'] is set.
If you want to run this database external to Omnibus, please follow the instructions below.
If you are using a cloud-managed service for the tracking database, you may need
to grant additional roles to your tracking database user (by default, this is
- Amazon RDS requires the
- Azure Database for PostgreSQL requires the
If you have an external database ready to be used as the tracking database, follow the instructions below to use it:
Ensure that your secondary node can communicate with your tracking database by manually changing the
pg_hba.confthat is associated with your tracking database. Remember to restart PostgreSQL afterwards for the changes to take effect:
## ## Geo Tracking Database Role ## - pg_hba.conf ## host all all <trusted tracking IP>/32 md5 host all all <trusted secondary IP>/32 md5
SSH into a GitLab secondary server and login as root:
/etc/gitlab/gitlab.rbwith the connection parameters and credentials for the machine with the PostgreSQL instance:
geo_secondary['db_username'] = 'gitlab_geo' geo_secondary['db_password'] = '<your_password_here>' geo_secondary['db_host'] = '<tracking_database_host>' geo_secondary['db_port'] = <tracking_database_port> # change to the correct port geo_postgresql['enable'] = false # don't use internal managed instance
Save the file and reconfigure GitLab
Run the tracking database migrations:
gitlab-rake geo:db:create gitlab-rake geo:db:migrate