Setting up Geo

Set up Geo to replicate a GitLab site to one or more secondary sites for disaster recovery and to bring data closer to distributed teams. Geo works on almost any supported GitLab architecture, but most deployments fit one of a few common shapes. To get started quickly, find the scenario that matches your deployment and follow the guide for it.

Prerequisites

Before you set up Geo, confirm the following:

• Two (or more) independently working GitLab sites:

  • One GitLab site serves as the Geo primary site. Use the GitLab reference architectures documentation to set this up. You can use different reference architecture sizes for each Geo site. If you already have a working GitLab instance that is in-use, it can be used as a primary site.

  • The second GitLab site serves as the Geo secondary site. Use the GitLab reference architectures documentation to set this up. It’s a good idea to sign in and test it. However, be aware that all of the data on the secondary are lost as part of the process of replicating from the primary site.

    Geo supports multiple secondaries. You can follow the same steps and make any changes accordingly.

• Administrator access for both sites. Many configuration tasks require root access to the sites and access to the Admin area in the GitLab UI.

• Ensure the primary site has a GitLab Premium or Ultimate subscription to unlock Geo. You only need one license for all the sites.

• Confirm the requirements for running Geo are met by all sites. For example, sites must use the same GitLab version, and sites must be able to communicate with each other over certain ports.

• Confirm the primary and secondary site storage configurations match. If the primary Geo site uses object storage, the secondary Geo site must use it too. For more information, see Geo with Object storage.

• Ensure clocks are synchronized between the primary site and the secondary site. Synchronized clocks are required for Geo to function correctly. For example, if the clock drift between the primary and secondary sites exceeds 1 minute, replication fails.

Choose your setup path

The following table lists the recommended guide for common deployments:

Cloud-native hybrid means you run GitLab in Kubernetes with the GitLab chart, but keep stateful components, such as PostgreSQL, outside the cluster.

If your deployment does not fit any of these rows, such as multi-node Linux package sites, see Other configurations.

After you complete the guide that matches your deployment, you might need additional configuration for LDAP, object storage, and the container registry, depending on how you use GitLab.

Set up cloud-native hybrid sites with a Patroni database

If your PostgreSQL databases run on a Patroni cluster outside Kubernetes, complete these steps in order:

1. Set up the databases with Multi-node database replication for the Patroni primary cluster, standby cluster, internal load balancer, and PgBouncer. On the secondary site, also configure the Geo tracking database.
2. Deploy the chart with the GitLab chart Geo guide for the application layer only. Skip its database steps. On each site, point global.psql.host at that site’s PgBouncer endpoint, or at the load balancer in front of your PgBouncer nodes. Do not point it at individual database nodes. On the secondary site, point global.geo.psql.host at the tracking database endpoint.

On the Patroni database nodes, use patroni_role. Do not use the geo_primary_role or geo_secondary_role convenience roles, which are intended only for single-node sites.

The Linux package does not support a highly available Geo tracking database. For high availability, use an external PostgreSQL service or a Patroni cluster that the Linux package does not manage. For more information, see configuring Patroni cluster for the tracking PostgreSQL database.

Other configurations

Use these configurations if your deployment does not match a row in the table.

Multi-node Linux package sites

If one or more of your sites uses the 40 RPS / 2,000 user reference architecture or larger, see Set up Geo for multiple nodes.

Build a path from the general steps

If no guide matches your deployment, you can assemble a path from the individual building blocks:

1. Set up the database replication based on your choice of PostgreSQL instances (primary (read-write) <-> secondary (read-only) topology):
   • Using Linux package PostgreSQL instances.
   • Using external PostgreSQL instances
2. Configure GitLab to set the primary and secondary sites.
3. Follow the Using a Geo Site guide.

Additional configuration

Depending on how you use GitLab, the following configuration might be required:

• If the primary site uses object storage, configure object storage replication for the secondary sites.
• If you use LDAP, configure a secondary LDAP server for the secondary sites. For more information, see LDAP with Geo.
• If you use the container registry, configure the container registry for replication on the primary and secondary sites.
• To speed up troubleshooting, configure correlation ID propagation.

You should configure unified URLs to use a single, unified URL for all Geo sites.

Geo and self-compiled installations

Geo is not supported when you use a self-compiled GitLab installation.

Post-installation documentation

After installing GitLab on the secondary sites and performing the initial configuration, see the following documentation for post-installation information.