Merge branch '3952-planned-failover-docs' into 'master'

Resolve "Geo DR: planned failover (including of a multi-node secondary)"

Closes #3952

See merge request gitlab-org/gitlab-ee!4920

doc/administration/geo/replication/configuration.md

@@ -143,7 +143,7 @@ keys must be manually replicated to the secondary node.
    'This is a primary node'.
 1. Optionally, choose which namespaces should be replicated by the
    secondary node. Leave blank to replicate all. Read more in
-   [selective replication](#selective-replication).
+   [selective synchronization](#selective-synchronization).
 1. Click the **Add node** button.
 1. SSH into your GitLab **secondary** server and restart the services:
 

doc/administration/geo/replication/configuration_source.md

@@ -96,7 +96,7 @@ Read [Manually replicate primary SSH host keys][configuration-replicate-ssh]
    'This is a primary node'.
 1. Optionally, choose which namespaces should be replicated by the
    secondary node. Leave blank to replicate all. Read more in
-   [selective replication](#selective-replication).
+   [selective synchronization](#selective-synchronization).
 1. Click the **Add node** button.
 1. SSH into your GitLab **secondary** server and restart the services:
 

doc/administration/geo/replication/index.md

@@ -203,13 +203,38 @@ extra limitations may be in place.
 
 - You cannot push code to secondary nodes, see [gitlab-org/gitlab-ee#3912] for details.
 - The primary node has to be online for OAuth login to happen (existing sessions and Git are not affected)
-- It works for repos, wikis, issues, merge requests, file attachments, artifacts and job logs but it does not work for, 
-  GitLab Pages, and Docker images of the Container Registry (by default, but you can configure it separately, 
-  see [replicate the Container Registry][docker-registry] for details).  
 - The installation takes multiple manual steps that together can take about an hour depending on circumstances; we are 
   working on improving this experience, see [gitlab-org/omnibus-gitlab#2978] for details.
 - Real-time updates of issues/merge requests (e.g. via long polling) doesn't work on the secondary
 - Broadcast messages set on the primary won't be seen on the secondary without a cache flush (e.g. gitlab-rake cache:clear)
+- [Selective synchronization](configuration.md#selective-synchronization)
+  applies only to files and repositories. Other datasets are replicated to the
+  secondary in full, making it inappropriate for use as an access control
+  mechanism.
+
+### Limitations on replication
+
+Only the following items are replicated to the secondary. Any data not on this
+list will not be available on the secondary, and failing over without manually
+replicating it will cause the data to be **lost**:
+
+- All database content (e.g., snippets, epics, issues, merge requests, groups, project metadata, etc)
+- Project repositories
+- Project wiki repositories
+- User uploads (e.g. attachments to issues, merge requests and epics, avatars, etc)
+- CI job artifacts and traces
+
+### Examples of unreplicated data
+
+Take special note that these GitLab features are both commonly used, and **not**
+replicated by Geo at present. If you wish to use them on the secondary, or to
+execute a failover successfully, you will need to replicate their data using
+some other means.
+
+- [Elasticsearch integration](../../../integration/elasticsearch.md)
+- [Container Registry](../../container_registry.md) ([Object Storage][docker-registry] can mitigate this)
+- [GitLab Pages](../../pages/index.md)
+- [Mattermost integration](https://docs.gitlab.com/omnibus/gitlab-mattermost/)
 
 ## Frequently Asked Questions
 

doc/administration/geo/replication/object_storage.md

@@ -18,7 +18,12 @@ For LFS, follow the documentation to
 For CI job artifacts, there is similar documentation to configure
 [jobs artifact object storage](../../job_artifacts.md#using-object-storage)
 
-Complete these steps on all nodes, primary **and** secondary.
+For user uploads, there is similar documentation to configure [upload object storage](../../uploads.md#using-object-storage)
+
+You should enable and configure object storage on both **primary** and **secondary**
+nodes. Migrating existing data to object storage should be performed on the
+**primary** node only; secondaries will automatically notice that the migrated
+files are now in object storage.
 
 ## Replication