Gitlab GEO: Bring Primary Back documentation process

Ola pessoal,

Hello everyone,

Here I am again, just one more question to make sure I have everything clear.

I’m going to run a Disaster Recovery test with the two GitLab instances I have configured with GEO. I will promote the secondary instance to primary as described here:
https://docs.gitlab.com/administration/geo/disaster_recovery/planned_failover/

I’ll carry out the required tests and, once everything is confirmed to be working, I’ll demote the former primary to secondary so it can sync back, as documented here:
https://docs.gitlab.com/administration/geo/disaster_recovery/bring_primary_back/

In this case, the documentation instructs to configure the former primary as if it were now the secondary.

I understand that in this process, since the former primary already had most of the required components—such as host keys, necessary PostgreSQL configurations, and certificates—it should only be necessary to configure items specific to a secondary node. For example, on the former primary, I’ll need to change the geo_primary_role to geo_secondary_role.

Is my reasoning correct on this?

I’m asking all of this because the documentation doesn’t make these details very clear, and I’m being extra careful to avoid wasted effort and, more importantly, to ensure a robust process when promoting everything to production.

Since I’m using Docker Compose, I’m adjusting the variables like the example below to ensure the template runs on the correct host and to avoid issues:

if ENV['GEO_ROLE'] == 'primary'

Duo's summary:

Documentation Improvements Needed:

1. Clarify Configuration Requirements: The documentation should explicitly state that when bringing a former primary back as a secondary, you primarily need to change role-specific configurations (like geo_primary_role to geo_secondary_role) rather than redoing the entire secondary setup.

2. Specify What Can Be Reused: Add clear guidance that existing components from the former primary can be retained:

   • Host keys
   • PostgreSQL configurations
   • Certificates
   • SSH keys
   • Other infrastructure components

3. Docker Compose Specific Guidance: Include examples for Docker Compose deployments, particularly around environment variable management like:

   if ENV['GEO_ROLE'] == 'primary'

   Insert at cursor

4. Step-by-Step Differentiation: Create a clearer distinction between:

   • Full secondary node setup (new installation)
   • Converting former primary to secondary (configuration changes only)

5. Practical Examples: Add more concrete examples showing the minimal changes needed when the former primary already has the required infrastructure components.