Add latest changes from gitlab-org/gitlab@15-2-stable-eev15.2.0-rc42

12 files changed, 98 insertions, 87 deletions

diff --git a/doc/administration/geo/disaster_recovery/background_verification.md b/doc/administration/geo/disaster_recovery/background_verification.md
index 57f8664ba11..97c9a6c5576 100644
--- a/doc/administration/geo/disaster_recovery/background_verification.md
+++ b/doc/administration/geo/disaster_recovery/background_verification.md
@@ -13,29 +13,25 @@ disable or enable this feature manually by following
 [these instructions](#disabling-or-enabling-the-automatic-background-verification).
 
 Automatic background verification ensures that the transferred data matches a
-calculated checksum. If the checksum of the data on the **primary** node matches checksum of the
-data on the **secondary** node, the data transferred successfully. Following a planned failover,
+calculated checksum. If the checksum of the data on the **primary** site matches checksum of the
+data on the **secondary** site, the data transferred successfully. Following a planned failover,
 any corrupted data may be **lost**, depending on the extent of the corruption.
 
-If verification fails on the **primary** node, this indicates Geo is replicating a corrupted object.
-You can restore it from backup or remove it from the **primary** node to resolve the issue.
+If verification fails on the **primary** site, this indicates Geo is replicating a corrupted object.
+You can restore it from backup or remove it from the **primary** site to resolve the issue.
 
-If verification succeeds on the **primary** node but fails on the **secondary** node,
+If verification succeeds on the **primary** site but fails on the **secondary** site,
 this indicates that the object was corrupted during the replication process.
 Geo actively try to correct verification failures marking the repository to
 be resynced with a back-off period. If you want to reset the verification for
 these failures, so you should follow [these instructions](background_verification.md#reset-verification-for-projects-where-verification-has-failed).
 
 If verification is lagging significantly behind replication, consider giving
-the node more time before scheduling a planned failover.
+the site more time before scheduling a planned failover.
 
 ## Disabling or enabling the automatic background verification
 
-Run the following commands in a Rails console on the **primary** node:
-
-```shell
-gitlab-rails console
-```
+Run the following commands in a [Rails console](../../operations/rails_console.md) on a **Rails node on the primary** site.
 
 To check if automatic background verification is enabled:
 
@@ -57,33 +53,33 @@ Feature.enable('geo_repository_verification')
 
 ## Repository verification
 
-On the **primary** node:
+On the **primary** site:
 
 1. On the top bar, select **Menu > Admin**.
-1. On the left sidebar, select **Geo > Nodes**.
-1. Expand **Verification information** tab for that node to view automatic checksumming
+1. On the left sidebar, select **Geo > Sites**.
+1. Expand **Verification information** tab for that site to view automatic checksumming
    status for repositories and wikis. Successes are shown in green, pending work
    in gray, and failures in red.
 
    ![Verification status](img/verification_status_primary_v14_0.png)
 
-On the **secondary** node:
+On the **secondary** site:
 
 1. On the top bar, select **Menu > Admin**.
-1. On the left sidebar, select **Geo > Nodes**.
-1. Expand **Verification information** tab for that node to view automatic checksumming
+1. On the left sidebar, select **Geo > Sites**.
+1. Expand **Verification information** tab for that site to view automatic checksumming
    status for repositories and wikis. Successes are shown in green, pending work
    in gray, and failures in red.
 
    ![Verification status](img/verification_status_secondary_v14_0.png)
 
-## Using checksums to compare Geo nodes
+## Using checksums to compare Geo sites
 
-To check the health of Geo **secondary** nodes, we use a checksum over the list of
+To check the health of Geo **secondary** sites, we use a checksum over the list of
 Git references and their values. The checksum includes `HEAD`, `heads`, `tags`,
-`notes`, and GitLab-specific references to ensure true consistency. If two nodes
+`notes`, and GitLab-specific references to ensure true consistency. If two sites
 have the same checksum, then they definitely hold the same references. We compute
-the checksum for every node after every update to make sure that they are all
+the checksum for every site after every update to make sure that they are all
 in sync.
 
 ## Repository re-verification
@@ -95,22 +91,17 @@ data. The default and recommended re-verification interval is 7 days, though
 an interval as short as 1 day can be set. Shorter intervals reduce risk but
 increase load and vice versa.
 
-On the **primary** node:
+On the **primary** site:
 
 1. On the top bar, select **Menu > Admin**.
-1. On the left sidebar, select **Geo > Nodes**.
-1. Select **Edit** for the **primary** node to customize the minimum
+1. On the left sidebar, select **Geo > Sites**.
+1. Select **Edit** for the **primary** site to customize the minimum
    re-verification interval:
 
    ![Re-verification interval](img/reverification-interval.png)
 
 The automatic background re-verification is enabled by default, but you can
-disable if you need. Run the following commands in a Rails console on the
-**primary** node:
-
-```shell
-gitlab-rails console
-```
+disable if you need. Run the following commands in a [Rails console](../../operations/rails_console.md) on a **Rails node on the primary** site:
 
 To disable automatic background re-verification:
 
@@ -126,11 +117,13 @@ Feature.enable('geo_repository_reverification')
 
 ## Reset verification for projects where verification has failed
 
-Geo actively try to correct verification failures marking the repository to
+Geo actively tries to correct verification failures marking the repository to
 be resynced with a back-off period. If you want to reset them manually, this
 Rake task marks projects where verification has failed or the checksum mismatch
 to be resynced without the back-off period:
 
+Run the appropriate commands on a **Rails node on the primary** site.
+
 For repositories:
 
 ```shell
@@ -145,9 +138,9 @@ sudo gitlab-rake geo:verification:wiki:reset
 
 ## Reconcile differences with checksum mismatches
 
-If the **primary** and **secondary** nodes have a checksum verification mismatch, the cause may not be apparent. To find the cause of a checksum mismatch:
+If the **primary** and **secondary** sites have a checksum verification mismatch, the cause may not be apparent. To find the cause of a checksum mismatch:
 
-1. On the **primary** node:
+1. On the **primary** site:
    1. On the top bar, select **Menu > Admin**.
    1. On the left sidebar, select **Overview > Projects**.
    1. Find the project that you want to check the checksum differences and
@@ -157,31 +150,32 @@ If the **primary** and **secondary** nodes have a checksum verification mismatch
 
       ![Project administration page](img/checksum-differences-admin-project-page.png)
 
-1. Go to the project's repository directory on both **primary** and **secondary** nodes
-   (the path is usually `/var/opt/gitlab/git-data/repositories`). If `git_data_dirs`
+1. On a **Gitaly node on the primary** site and a **Gitaly node on the secondary** site, go to the project's repository directory. If using Gitaly Cluster, [check that it is in a healthy state](../../gitaly/troubleshooting.md#check-cluster-health) prior to running these commands.
+
+   The default path is `/var/opt/gitlab/git-data/repositories`. If `git_data_dirs`
    is customized, check the directory layout on your server to be sure:
 
    ```shell
    cd /var/opt/gitlab/git-data/repositories
    ```
 
-1. Run the following command on the **primary** node, redirecting the output to a file:
+   1. Run the following command on the **primary** site, redirecting the output to a file:
 
-   ```shell
-   git show-ref --head | grep -E "HEAD|(refs/(heads|tags|keep-around|merge-requests|environments|notes)/)" > primary-node-refs
-   ```
+      ```shell
+      git show-ref --head | grep -E "HEAD|(refs/(heads|tags|keep-around|merge-requests|environments|notes)/)" > primary-site-refs
+      ```
 
-1. Run the following command on the **secondary** node, redirecting the output to a file:
+   1. Run the following command on the **secondary** site, redirecting the output to a file:
 
-   ```shell
-   git show-ref --head | grep -E "HEAD|(refs/(heads|tags|keep-around|merge-requests|environments|notes)/)" > secondary-node-refs
-   ```
+      ```shell
+      git show-ref --head | grep -E "HEAD|(refs/(heads|tags|keep-around|merge-requests|environments|notes)/)" > secondary-site-refs
+      ```
 
-1. Copy the files from the previous steps on the same system, and do a diff between the contents:
+   1. Copy the files from the previous steps on the same system, and do a diff between the contents:
 
-   ```shell
-   diff primary-node-refs secondary-node-refs
-   ```
+      ```shell
+      diff primary-site-refs secondary-site-refs
+      ```
 
 ## Current limitations
 
@@ -191,10 +185,10 @@ progress to include them in [Geo: Verify all replicated data](https://gitlab.com
 
 For now, you can verify their integrity
 manually by following [these instructions](../../raketasks/check.md) on both
-nodes, and comparing the output between them.
+sites, and comparing the output between them.
 
 In GitLab EE 12.1, Geo calculates checksums for attachments, LFS objects, and
-archived traces on secondary nodes after the transfer, compares it with the
+archived traces on secondary sites after the transfer, compares it with the
 stored checksums, and rejects transfers if mismatched. Geo
 currently does not support an automatic way to verify these data if they have
 been synced before GitLab EE 12.1.
diff --git a/doc/administration/geo/disaster_recovery/index.md b/doc/administration/geo/disaster_recovery/index.md
index e5b9a14cfbd..f457cb4b0a2 100644
--- a/doc/administration/geo/disaster_recovery/index.md
+++ b/doc/administration/geo/disaster_recovery/index.md
@@ -413,7 +413,7 @@ required:
 1. Promote the replica database associated with the **secondary** site. This
    sets the database to read-write. The instructions vary depending on where your database is hosted:
    - [Amazon RDS](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_ReadRepl.html#USER_ReadRepl.Promote)
-   - [Azure PostgreSQL](https://docs.microsoft.com/en-us/azure/postgresql/howto-read-replicas-portal#stop-replication)
+   - [Azure PostgreSQL](https://docs.microsoft.com/en-us/azure/postgresql/single-server/how-to-read-replicas-portal#stop-replication)
    - [Google Cloud SQL](https://cloud.google.com/sql/docs/mysql/replication/manage-replicas#promote-replica)
    - For other external PostgreSQL databases, save the following script in your
      secondary site, for example `/tmp/geo_promote.sh`, and modify the connection
diff --git a/doc/administration/geo/disaster_recovery/planned_failover.md b/doc/administration/geo/disaster_recovery/planned_failover.md
index c351b4031b5..5a5d896c20a 100644
--- a/doc/administration/geo/disaster_recovery/planned_failover.md
+++ b/doc/administration/geo/disaster_recovery/planned_failover.md
@@ -60,8 +60,8 @@ Alternatively, you can [back up](../../../raketasks/backup_restore.md#back-up-gi
 the container registry on the primary site and restore it onto the secondary
 site:
 
-1. On your primary site, back up only the registry and [exclude specific directories
-from the backup](../../../raketasks/backup_restore.md#excluding-specific-directories-from-the-backup):
+1. On your primary site, back up only the registry and
+   [exclude specific directories from the backup](../../../raketasks/backup_gitlab.md#excluding-specific-directories-from-the-backup):
 
    ```shell
    # Create a backup in the /var/opt/gitlab/backups folder
diff --git a/doc/administration/geo/index.md b/doc/administration/geo/index.md
index c5472e412d3..cf7d2649142 100644
--- a/doc/administration/geo/index.md
+++ b/doc/administration/geo/index.md
@@ -123,7 +123,7 @@ The following are required to run Geo:
   - PostgreSQL 13 is not supported for Geo, see [epic 3832](https://gitlab.com/groups/gitlab-org/-/epics/3832)
 - Git 2.9 or later
 - Git-lfs 2.4.2 or later on the user side when using LFS
-- All sites must run the same GitLab version.
+- All sites must run [the same GitLab and PostgreSQL versions](setup/database.md#postgresql-replication).
 
 Additionally, check the GitLab [minimum requirements](../../install/requirements.md),
 and we recommend you use the latest version of GitLab for a better experience.
diff --git a/doc/administration/geo/replication/configuration.md b/doc/administration/geo/replication/configuration.md
index 043b96478c9..7666a450648 100644
--- a/doc/administration/geo/replication/configuration.md
+++ b/doc/administration/geo/replication/configuration.md
@@ -12,7 +12,9 @@ type: howto
 NOTE:
 This is the final step in setting up a **secondary** Geo site. Stages of the
 setup process must be completed in the documented order.
-Before attempting the steps in this stage, [complete all prior stages](../setup/index.md#using-omnibus-gitlab).
+If not, [complete all prior stages](../setup/index.md#using-omnibus-gitlab) before procceed.
+
+Make sure you [set up the database replication](../setup/database.md), and [configured fast lookup of authorized SSH keys](../../operations/fast_ssh_key_lookup.md) in **both primary and secondary sites**.
 
 The basic steps of configuring a **secondary** site are to:
 
@@ -318,7 +320,7 @@ the **primary** site. After you sign in:
 1. Verify that it's correctly identified as a **secondary** Geo site, and that
    Geo is enabled.
 
-The initial replication, or 'backfill', is probably still in progress. You
+The initial replication may take some time. The status of the site or the ‘backfill’ may still in progress. You
 can monitor the synchronization process on each Geo site from the **primary**
 site's **Geo Sites** dashboard in your browser.
 
diff --git a/doc/administration/geo/replication/datatypes.md b/doc/administration/geo/replication/datatypes.md
index e49d5260233..acd27d5feed 100644
--- a/doc/administration/geo/replication/datatypes.md
+++ b/doc/administration/geo/replication/datatypes.md
@@ -202,8 +202,8 @@ successfully, you must replicate their data using some other means.
 |[External merge request diffs](../../merge_request_diffs.md)                                                   | **Yes** (13.5)                                                          | **Yes** (14.6)                                                             | [**Yes** (15.1)](https://gitlab.com/groups/gitlab-org/-/epics/5551) | [No](object_storage.md#verification-of-files-in-object-storage) | Replication is behind the feature flag `geo_merge_request_diff_replication`, enabled by default. Verification was behind the feature flag `geo_merge_request_diff_verification`, removed in 14.7.|
 |[Versioned snippets](../../../user/snippets.md#versioned-snippets)                                             | [**Yes** (13.7)](https://gitlab.com/groups/gitlab-org/-/epics/2809)     | [**Yes** (14.2)](https://gitlab.com/groups/gitlab-org/-/epics/2810)        | N/A                                                                 | N/A                                                             | Verification was implemented behind the feature flag `geo_snippet_repository_verification` in 13.11, and the feature flag was removed in 14.2. |
 |[GitLab Pages](../../pages/index.md)                                                                           | [**Yes** (14.3)](https://gitlab.com/groups/gitlab-org/-/epics/589)      | **Yes** (14.6)                                                             | [**Yes** (15.1)](https://gitlab.com/groups/gitlab-org/-/epics/5551) | [No](object_storage.md#verification-of-files-in-object-storage) | Behind feature flag `geo_pages_deployment_replication`, enabled by default. Verification was behind the feature flag `geo_pages_deployment_verification`, removed in 14.7. |
-|[Incident Metric Images](../../../operations/incident_management/incidents.md#metrics)                         | [Planned](https://gitlab.com/gitlab-org/gitlab/-/issues/352326)         | [No](https://gitlab.com/gitlab-org/gitlab/-/issues/362561)                 | No                                                                  | No                                                              | |
-|[Alert Metric Images](../../../operations/incident_management/alerts.md#metrics-tab)                           | [Planned](https://gitlab.com/gitlab-org/gitlab/-/issues/352326)         | [No](https://gitlab.com/gitlab-org/gitlab/-/issues/362561)                 | No                                                                  | No                                                              | |
+|[Incident Metric Images](../../../operations/incident_management/incidents.md#metrics)                         | [Planned](https://gitlab.com/gitlab-org/gitlab/-/issues/362561)         | [No](https://gitlab.com/gitlab-org/gitlab/-/issues/362561)                 | No                                                                  | No                                                              | |
+|[Alert Metric Images](../../../operations/incident_management/alerts.md#metrics-tab)                           | [Planned](https://gitlab.com/gitlab-org/gitlab/-/issues/362564)         | [No](https://gitlab.com/gitlab-org/gitlab/-/issues/362564)                 | No                                                                  | No                                                              | |
 |[Server-side Git hooks](../../server_hooks.md)                                                                 | [Not planned](https://gitlab.com/groups/gitlab-org/-/epics/1867)        | No                                                                         | N/A                                                                 | N/A                                                             | Not planned because of current implementation complexity, low customer interest, and availability of alternatives to hooks. |
 |[Elasticsearch integration](../../../integration/elasticsearch.md)                                             | [Not planned](https://gitlab.com/gitlab-org/gitlab/-/issues/1186)       | No                                                                         | No                                                                  | No                                                              | Not planned because further product discovery is required and Elasticsearch (ES) clusters can be rebuilt. Secondaries use the same ES cluster as the primary. |
 |[Dependency proxy images](../../../user/packages/dependency_proxy/index.md)                                    | [Not planned](https://gitlab.com/gitlab-org/gitlab/-/issues/259694)     | No                                                                         | No                                                                  | No                                                              | Blocked by [Geo: Secondary Mimicry](https://gitlab.com/groups/gitlab-org/-/epics/1528). Replication of this cache is not needed for disaster recovery purposes because it can be recreated from external sources. |
diff --git a/doc/administration/geo/replication/object_storage.md b/doc/administration/geo/replication/object_storage.md
index dd1f982b3a1..d2e10678f8c 100644
--- a/doc/administration/geo/replication/object_storage.md
+++ b/doc/administration/geo/replication/object_storage.md
@@ -34,8 +34,7 @@ See [Object storage replication tests](geo_validation_tests.md#object-storage-re
 
 ## Enabling GitLab-managed object storage replication
 
-> The beta feature was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10586) in GitLab 12.4.
-> The feature was made [generally available] in GitLab 15.1.
+> The feature was made [generally available](https://gitlab.com/groups/gitlab-org/-/epics/5551) in GitLab 15.1.
 
 **Secondary** sites can replicate files stored on the **primary** site regardless of
 whether they are stored on the local file system or in object storage.
@@ -79,7 +78,7 @@ the bucket used by **secondary** sites.
 
 If you are using Google Cloud Storage, consider using
 [Multi-Regional Storage](https://cloud.google.com/storage/docs/storage-classes#multi-regional).
-Or you can use the [Storage Transfer Service](https://cloud.google.com/storage-transfer/docs/),
+Or you can use the [Storage Transfer Service](https://cloud.google.com/storage-transfer/docs/overview),
 although this only supports daily synchronization.
 
 For manual synchronization, or scheduled by `cron`, see:
diff --git a/doc/administration/geo/replication/troubleshooting.md b/doc/administration/geo/replication/troubleshooting.md
index bb7dbef214b..082ecbbb208 100644
--- a/doc/administration/geo/replication/troubleshooting.md
+++ b/doc/administration/geo/replication/troubleshooting.md
@@ -183,7 +183,7 @@ This machine's Geo node name matches a database record ... no
 ```
 
 Learn more about recommended site names in the description of the Name field in
-[Geo Admin Area Common Settings](../../../user/admin_area/geo_nodes.md#common-settings).
+[Geo Admin Area Common Settings](../../../user/admin_area/geo_sites.md#common-settings).
 
 ### Message: `WARNING: oldest xmin is far in the past` and `pg_wal` size growing
 
@@ -519,7 +519,7 @@ To solve this:
    curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/<first_failed_geo_sync_ID>"
    ```
 
-1. Enter the [Rails console](../../troubleshooting/navigating_gitlab_via_rails_console.md) and run:
+1. Enter the [Rails console](../../operations/rails_console.md) and run:
 
    ```ruby
    failed_geo_syncs = Geo::ProjectRegistry.failed.pluck(:id)
@@ -651,8 +651,11 @@ to start again from scratch, there are a few steps that can help you:
 
 1. Reset the Tracking Database.
 
+   WARNING:
+   If you skipped the optional step 3, be sure both `geo-postgresql` and `postgresql` services are running.
+
    ```shell
-   gitlab-rake db:drop:geo    # on a secondary app node
+   gitlab-rake db:drop:geo DISABLE_DATABASE_ENVIRONMENT_CHECK=1   # on a secondary app node
    gitlab-ctl reconfigure     # on the tracking database node
    gitlab-rake db:migrate:geo # on a secondary app node
    ```
@@ -805,7 +808,7 @@ You can work around this by marking the objects as synced and succeeded verifica
 be aware that can also mark objects that may be
 [missing from the primary](#missing-files-on-the-geo-primary-site).
 
-To do that, enter the [Rails console](../../troubleshooting/navigating_gitlab_via_rails_console.md)
+To do that, enter the [Rails console](../../operations/rails_console.md)
 and run:
 
 ```ruby
@@ -817,16 +820,16 @@ end
 
 ### Message: curl 18 transfer closed with outstanding read data remaining & fetch-pack: unexpected disconnect while reading sideband packet
 
-Unstable networking conditions can cause Gitaly to fail when trying to fetch large repository 
+Unstable networking conditions can cause Gitaly to fail when trying to fetch large repository
 data from the primary site. This is more likely to happen if a repository has to be
 replicated from scratch between sites.
 
 Geo retries several times, but if the transmission is consistently interrupted
-by network hiccups, an alternative method such as `rsync` can be used to circumvent `git` and 
+by network hiccups, an alternative method such as `rsync` can be used to circumvent `git` and
 create the initial copy of any repository that fails to be replicated by Geo.
 
 We recommend transferring each failing repository individually and checking for consistency
-after each transfer. Follow the [single target `rsync` instructions](../../operations/moving_repositories.md#single-rsync-to-another-server) 
+after each transfer. Follow the [single target `rsync` instructions](../../operations/moving_repositories.md#single-rsync-to-another-server)
 to transfer each affected repository from the primary to the secondary site.
 
 ## Fixing errors during a failover or when promoting a secondary to a primary node
diff --git a/doc/administration/geo/secondary_proxy/index.md b/doc/administration/geo/secondary_proxy/index.md
index 9a1aab8c238..e8c290e197b 100644
--- a/doc/administration/geo/secondary_proxy/index.md
+++ b/doc/administration/geo/secondary_proxy/index.md
@@ -124,7 +124,7 @@ sudo gitlab-rails runner "Feature.disable(:geo_secondary_proxy_separate_urls)"
 ```
 
 In Kubernetes, you can run the same command in the toolbox pod. Refer to the
-[Kubernetes cheat sheet](../../troubleshooting/kubernetes_cheat_sheet.md#gitlab-specific-kubernetes-information)
+[Kubernetes cheat sheet](https://docs.gitlab.com/charts/troubleshooting/kubernetes_cheat_sheet.html#gitlab-specific-kubernetes-information)
 for details.
 
 ## Limitations
diff --git a/doc/administration/geo/setup/database.md b/doc/administration/geo/setup/database.md
index 7dfca4c8f73..c0ed7829fce 100644
--- a/doc/administration/geo/setup/database.md
+++ b/doc/administration/geo/setup/database.md
@@ -17,8 +17,11 @@ PostgreSQL instances, the Omnibus roles cannot perform all necessary
 configuration steps. In this case, use the [Geo with external PostgreSQL instances](external_database.md)
 process instead.
 
+NOTE:
 The stages of the setup process must be completed in the documented order.
-Before you attempt the steps in this stage, [complete all prior stages](../setup/index.md#using-omnibus-gitlab).
+If not, [complete all prior stages](../setup/index.md#using-omnibus-gitlab) before proceeding.
+
+Ensure the **secondary** site is running the same version of GitLab Enterprise Edition as the **primary** site. Confirm you have added the [premium or higher licenses](https://about.gitlab.com/pricing/) to your **primary** site.
 
 Be sure to read and review all of these steps before you execute them in your
 testing or production environments.
@@ -52,8 +55,9 @@ The following guide assumes that:
   which includes the [`pg_basebackup` tool](https://www.postgresql.org/docs/12/app-pgbasebackup.html).
 - You have a **primary** node already set up (the GitLab server you are
   replicating from), running Omnibus' PostgreSQL (or equivalent version), and
-  you have a new **secondary** server set up with the same versions of the OS,
-  PostgreSQL, and GitLab on all nodes.
+  you have a new **secondary** server set up with the same
+  [versions of PostgreSQL](../index.md#requirements-for-running-geo),
+  OS, and GitLab on all nodes.
 
 WARNING:
 Geo works with streaming replication. Logical replication is not supported at this time.
@@ -478,7 +482,7 @@ data before running `pg_basebackup`.
    ```shell
    gitlab-ctl replicate-geo-database \
       --slot-name=<secondary_node_name> \
-      --host=<primary_node_ip>
+      --host=<primary_node_ip> \
       --sslmode=verify-ca
    ```
 
diff --git a/doc/administration/geo/setup/external_database.md b/doc/administration/geo/setup/external_database.md
index 7e8ffa829f9..b87baa658a1 100644
--- a/doc/administration/geo/setup/external_database.md
+++ b/doc/administration/geo/setup/external_database.md
@@ -10,14 +10,19 @@ This document is relevant if you are using a PostgreSQL instance that is *not
 managed by Omnibus*. This includes cloud-managed instances like Amazon RDS, or
 manually installed and configured PostgreSQL instances.
 
+Ensure that you are using one of the PostgreSQL versions that
+[Omnibus ships with](../../package_information/postgresql_versions.md)
+to [avoid version mismatches](../index.md#requirements-for-running-geo)
+in case a Geo site has to be rebuilt.
+
 NOTE:
 We strongly recommend running Omnibus-managed instances as they are actively
 developed and tested. We aim to be compatible with most external
 (not managed by Omnibus) databases but we do not guarantee compatibility.
 
-## **Primary** node
+## **Primary** site
 
-1. SSH into a GitLab **primary** application server and login as root:
+1. SSH into a **Rails node on your primary** site and login as root:
 
    ```shell
    sudo -i
@@ -39,13 +44,13 @@ developed and tested. We aim to be compatible with most external
    gitlab_rails['geo_node_name'] = '<site_name_here>'
    ```
 
-1. Reconfigure the **primary** node for the change to take effect:
+1. Reconfigure the **Rails node** for the change to take effect:
 
    ```shell
    gitlab-ctl reconfigure
    ```
 
-1. Execute the command below to define the node as **primary** node:
+1. Execute the command below on the **Rails node** to define the site as **primary** site:
 
    ```shell
    gitlab-ctl set-geo-primary-node
@@ -62,10 +67,10 @@ To set up an external database, you can either:
 
 #### Leverage your cloud provider's tools to replicate the primary database
 
-Given you have a primary node set up on AWS EC2 that uses RDS.
+Given you have a primary site 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 is managed by AWS. Make sure you've set Network ACL (Access Control List), Subnet, and
-Security Group according to your needs, so the secondary application node can access the database.
+Security Group according to your needs, so the secondary Rails node(s) can access the database.
 
 The following instructions detail how to create a read-only replica for common
 cloud providers:
@@ -74,7 +79,7 @@ cloud providers:
 - Azure Database for PostgreSQL - [Create and manage read replicas in Azure Database for PostgreSQL](https://docs.microsoft.com/en-us/azure/postgresql/single-server/how-to-read-replicas-portal)
 - Google Cloud SQL - [Creating read replicas](https://cloud.google.com/sql/docs/postgres/replication/create-replica)
 
-Once your read-only replica is set up, you can skip to [configure your secondary application node](#configure-secondary-application-nodes-to-use-the-external-read-replica).
+Once your read-only replica is set up, you can skip to [configure your secondary site](#configure-secondary-site-to-use-the-external-read-replica)
 
 #### Manually configure the primary database for replication
 
@@ -107,7 +112,7 @@ max_replication_slots = 1 # number of secondary instances
 hot_standby = on
 ```
 
-## **Secondary** nodes
+## **Secondary** sites
 
 ### Manually configure the replica database
 
@@ -136,7 +141,7 @@ wal_keep_segments = 10
 hot_standby = on
 ```
 
-### Configure **secondary** application nodes to use the external read-replica
+### Configure **secondary** site to use the external read-replica
 
 With Omnibus, the
 [`geo_secondary_role`](https://docs.gitlab.com/omnibus/roles/#gitlab-geo-roles)
@@ -148,7 +153,7 @@ has three main functions:
 
 To configure the connection to the external read-replica database and enable Log Cursor:
 
-1. SSH into a GitLab **secondary** application server and login as root:
+1. SSH into each **Rails, Sidekiq and Geo Log Cursor** node on your **secondary** site and login as root:
 
    ```shell
    sudo -i
@@ -179,7 +184,7 @@ To configure the connection to the external read-replica database and enable Log
 
 ### Configure the tracking database
 
-**Secondary** nodes use a separate PostgreSQL installation as a tracking
+**Secondary** sites 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
 when `roles ['geo_secondary_role']` is set.
@@ -209,7 +214,7 @@ the tracking database on port 5432.
    [database requirements document](../../../install/requirements.md#database).
 1. Set up a `gitlab_geo` user with a password of your choice, create the `gitlabhq_geo_production` database, and make the user an owner of the database. You can see an example of this setup in the [installation from source documentation](../../../install/installation.md#6-database).
 1. If you are **not** using a cloud-managed PostgreSQL database, ensure that your secondary
-   node can communicate with your tracking database by manually changing the
+   site can communicate with your tracking database by manually changing the
    `pg_hba.conf` that is associated with your tracking database.
    Remember to restart PostgreSQL afterwards for the changes to take effect:
 
diff --git a/doc/administration/geo/setup/index.md b/doc/administration/geo/setup/index.md
index f4c21293782..5ddfee6774e 100644
--- a/doc/administration/geo/setup/index.md
+++ b/doc/administration/geo/setup/index.md
@@ -12,21 +12,25 @@ These instructions assume you have a working instance of GitLab. They guide you
 1. Making your existing instance the **primary** site.
 1. Adding **secondary** sites.
 
+You must use a [GitLab Premium](https://about.gitlab.com/pricing/) license or higher,
+but you only need one license for all the sites.
+
 WARNING:
-The steps below should be followed in the order they appear. **Make sure the GitLab version is the same on all sites.**
+The steps below should be followed in the order they appear. **Make sure the GitLab version is the same on all sites. Do not create an account or log in to the new secondary.**
 
 ## Using Omnibus GitLab
 
 If you installed GitLab using the Omnibus packages (highly recommended):
 
-1. [Install GitLab Enterprise Edition](https://about.gitlab.com/install/) on the nodes that serve as the **secondary** site. Do not create an account or log in to the new **secondary** site. The **GitLab version must match** across primary and secondary sites.
+1. [Install GitLab Enterprise Edition](https://about.gitlab.com/install/) on the nodes that serve as the **secondary** site. **Do not create an account or log in** to the new **secondary** site. The **GitLab version must match** across primary and secondary sites.
 1. [Add the GitLab License](../../../user/admin_area/license.md) on the **primary** site to unlock Geo. The license must be for [GitLab Premium](https://about.gitlab.com/pricing/) or higher.
 1. [Set up the database replication](database.md) (`primary (read-write) <-> secondary (read-only)` topology).
 1. [Configure fast lookup of authorized SSH keys in the database](../../operations/fast_ssh_key_lookup.md). This step is required and needs to be done on **both** the **primary** and **secondary** sites.
 1. [Configure GitLab](../replication/configuration.md) to set the **primary** and **secondary** sites.
+1. Optional: [Configure Object storage](../../object_storage.md)
 1. Optional: [Configure a secondary LDAP server](../../auth/ldap/index.md) for the **secondary** sites. See [notes on LDAP](../index.md#ldap).
+1. Optional: [Configure Geo secondary proxying](../secondary_proxy/index.md) to use a single, unified URL for all Geo sites. This step is recommended to accelerate most read requests while transparently proxying writes to the primary Geo site.
 1. Follow the [Using a Geo Site](../replication/usage.md) guide.
-1. [Configure Geo secondary proxying](../secondary_proxy/index.md) to use a single, unified URL for all Geo sites. This step is recommended to accelerate most read requests while transparently proxying writes to the primary Geo site.
 
 ## Post-installation documentation