Setting up Geo

Tier: Premium, Ultimate Offering: Self-managed

Prerequisites

  • 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.
    note
    Geo supports multiple secondaries. You can follow the same steps and make any changes accordingly.
  • 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.

Using Linux package installations

If you installed GitLab using the Linux package (highly recommended), the process for setting up Geo depends on whether you need to set up a single-node Geo site or a multi-node Geo site.

Single-node Geo sites

If both Geo sites are based on the 1K reference architecture, follow Set up Geo for two single-node sites.

If using external PostgreSQL services, for example Amazon RDS, follow Set up Geo for two single-node sites (with external PostgreSQL services).

Depending on your GitLab deployment, additional configuration for LDAP, object storage, and the container registry might be required.

Multi-node Geo sites

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

Depending on your GitLab deployment, additional configuration for LDAP, object storage, and the container registry might be required.

General steps for reference

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

Depending on your GitLab deployment, additional configuration for LDAP, object storage, and the container registry might be required.

Additional configuration

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

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

Using GitLab Charts

Configure the GitLab chart with GitLab Geo.

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.