Add latest changes from gitlab-org/gitlab@master

3 files changed, 22 insertions, 10 deletions

diff --git a/doc/administration/geo/replication/multiple_servers.md b/doc/administration/geo/replication/multiple_servers.md
index 850ab9f0707..9298281561f 100644
--- a/doc/administration/geo/replication/multiple_servers.md
+++ b/doc/administration/geo/replication/multiple_servers.md
@@ -61,6 +61,9 @@ The following steps enable a GitLab site to serve as the Geo **primary** site.
 
 ### Step 1: Configure the **primary** frontend nodes
 
+NOTE:
+Avoid using [`geo_primary_role`](https://docs.gitlab.com/omnibus/roles/#gitlab-geo-roles) because it is intended for a single-node site.
+
 1. Edit `/etc/gitlab/gitlab.rb` and add the following:
 
    ```ruby
@@ -126,14 +129,7 @@ NOTE:
 [NFS](../../nfs.md) can be used in place of Gitaly but is not
 recommended.
 
-### Step 2: Configure PostgreSQL streaming replication
-
-Follow the [Geo database replication instructions](../setup/database.md).
-
-If using an external PostgreSQL instance, refer also to
-[Geo with external PostgreSQL instances](../setup/external_database.md).
-
-### Step 3: Configure the Geo tracking database on the Geo **secondary** site
+### Step 2: Configure the Geo tracking database on the Geo **secondary** site
 
 If you want to run the Geo tracking database in a multi-node PostgreSQL cluster,
 then follow [Configuring Patroni cluster for the tracking PostgreSQL database](../setup/database.md#configuring-patroni-cluster-for-the-tracking-postgresql-database).
@@ -183,8 +179,20 @@ After making these changes, [reconfigure GitLab](../../restart_gitlab.md#reconfi
 If using an external PostgreSQL instance, refer also to
 [Geo with external PostgreSQL instances](../setup/external_database.md).
 
+### Step 3: Configure PostgreSQL streaming replication
+
+Follow the [Geo database replication instructions](../setup/database.md).
+
+If using an external PostgreSQL instance, refer also to
+[Geo with external PostgreSQL instances](../setup/external_database.md).
+
+After streaming replication is enabled in the secondary Geo site's read-replica database, then commands such as `gitlab-rake db:migrate:status:geo` will fail, until [configuration of the secondary site is complete](#step-7-copy-secrets-and-add-the-secondary-site-in-the-application), specifically [Geo configuration - Step 3. Add the secondary site](configuration.md#step-3-add-the-secondary-site).
+
 ### Step 4: Configure the frontend application nodes on the Geo **secondary** site
 
+NOTE:
+Avoid using [`geo_secondary_role`](https://docs.gitlab.com/omnibus/roles/#gitlab-geo-roles) because it is intended for a single-node site.
+
 In the minimal [architecture diagram](#architecture-overview) above, there are two
 machines running the GitLab application services. These services are enabled
 selectively in the configuration.
@@ -364,3 +372,7 @@ application nodes above, with some changes to run only the `sidekiq` service:
    `sidekiq['enable'] = false`.
 
    These nodes do not need to be attached to the load balancer.
+
+### Step 7: Copy secrets and add the secondary site in the application
+
+1. [Configure GitLab](configuration.md) to set the **primary** and **secondary** sites.
diff --git a/doc/administration/geo/replication/troubleshooting.md b/doc/administration/geo/replication/troubleshooting.md
index 6e60ae34a22..39fa04103db 100644
--- a/doc/administration/geo/replication/troubleshooting.md
+++ b/doc/administration/geo/replication/troubleshooting.md
@@ -337,7 +337,7 @@ sudo gitlab-rake gitlab:geo:check
   ```
 
   - If you are running the secondary site on a single node for all services, then follow [Geo database replication - Configure the secondary server](../setup/database.md#step-2-configure-the-secondary-server).
-  - If you are running the secondary site's tracking database on its own node, then follow [Geo for multiple servers - Configure the Geo tracking database on the Geo secondary site](multiple_servers.md#step-3-configure-the-geo-tracking-database-on-the-geo-secondary-site)
+  - If you are running the secondary site's tracking database on its own node, then follow [Geo for multiple servers - Configure the Geo tracking database on the Geo secondary site](multiple_servers.md#step-2-configure-the-geo-tracking-database-on-the-geo-secondary-site)
   - If you are running the secondary site's tracking database in a Patroni cluster, then follow [Geo database replication - Configure the tracking database on the secondary sites](../setup/database.md#step-3-configure-the-tracking-database-on-the-secondary-sites)
   - If you are running the secondary site's tracking database in an external database, then follow [Geo with external PostgreSQL instances](../setup/external_database.md#configure-the-tracking-database)
   - If the Geo check task was run on a node which is not running a service which runs the GitLab Rails app (Puma, Sidekiq, or Geo Log Cursor), then this error can be ignored. The node does not need Rails to be configured.
diff --git a/doc/administration/geo/setup/database.md b/doc/administration/geo/setup/database.md
index b9c2a69eaf7..a9238a4142a 100644
--- a/doc/administration/geo/setup/database.md
+++ b/doc/administration/geo/setup/database.md
@@ -950,7 +950,7 @@ The Linux package automatically configures a tracking database when `roles(['geo
 If you want to run this database in a highly available configuration, don't use the `geo_secondary_role` above.
 Instead, follow the instructions below.
 
-If you want to run the Geo tracking database on a single node, see [Configure the Geo tracking database on the Geo secondary site](../replication/multiple_servers.md#step-3-configure-the-geo-tracking-database-on-the-geo-secondary-site).
+If you want to run the Geo tracking database on a single node, see [Configure the Geo tracking database on the Geo secondary site](../replication/multiple_servers.md#step-2-configure-the-geo-tracking-database-on-the-geo-secondary-site).
 
 A production-ready and secure setup for the tracking PostgreSQL DB requires at least three Consul nodes: two
 Patroni nodes, and one PgBouncer node on the secondary site.