Merge branch '14779-update-documentation-for-replication-from-object-storage-docs' into 'master'

Update documentation for replication from Object Storage

Closes #14779

See merge request gitlab-org/gitlab!18276

doc/administration/geo/disaster_recovery/planned_failover.md

@@ -43,23 +43,14 @@ will go smoothly.
 
 ### Object storage
 
-Some classes of non-repository data can use object storage in preference to
-file storage. Geo [does not replicate data in object storage](../replication/object_storage.md),
-leaving that task up to the object store itself. For a planned failover, this
-means you can decouple the replication of this data from the failover of the
-GitLab service.
-
-If you're already using object storage, simply verify that your **secondary**
-node has access to the same data as the **primary** node - they must either they share the
-same object storage configuration, or the **secondary** node should be configured to
-access a [geographically-replicated][os-repl] copy provided by the object store
-itself.
-
 If you have a large GitLab installation or cannot tolerate downtime, consider
 [migrating to Object Storage][os-conf] **before** scheduling a planned failover.
 Doing so reduces both the length of the maintenance window, and the risk of data
 loss as a result of a poorly executed planned failover.
 
+In GitLab 12.4, you can optionally allow GitLab to manage replication of Object Storage for
+**secondary** nodes. For more information, see [Object Storage replication][os-conf].
+
 ### Review the configuration of each **secondary** node
 
 Database settings are automatically replicated to the **secondary**  node, but the
@@ -224,5 +215,4 @@ Don't forget to remove the broadcast message after failover is complete.
 [background-verification]: background_verification.md
 [limitations]: ../replication/index.md#current-limitations
 [moving-repositories]: ../../operations/moving_repositories.md
-[os-conf]: ../replication/object_storage.md#configuration
-[os-repl]: ../replication/object_storage.md#replication
+[os-conf]: ../replication/object_storage.md

doc/administration/geo/replication/index.md

@@ -283,7 +283,6 @@ You can keep track of the progress to include the missing items in:
 | [Maven Packages](../../../user/packages/maven_repository/index.md) | No | No |
 | [Conan Packages](../../../user/packages/conan_repository/index.md) | No | No |
 | [External merge request diffs](../../merge_request_diffs.md) | No, if they are on-disk | No |
-| Content in object storage ([track progress](https://gitlab.com/groups/gitlab-org/-/epics/1526)) | No | No |
 
 1. The integrity can be verified manually using [Integrity Check Rake Task](../../raketasks/check.md) on both nodes and comparing the output between them.
 

doc/administration/geo/replication/object_storage.md

 # Geo with Object storage **(PREMIUM ONLY)**
 
-Geo can be used in combination with Object Storage (AWS S3, or
-other compatible object storage).
+Geo can be used in combination with Object Storage (AWS S3, or other compatible object storage).
 
-## Configuration
+Currently, **secondary** nodes can use either:
 
-At this time it is required that if object storage is enabled on the
-**primary** node, it must also be enabled on each **secondary** node.
+- The same storage bucket as the **primary** node.
+- A replicated storage bucket.
 
-**Secondary** nodes can use the same storage bucket as the **primary** node, or
-they can use a replicated storage bucket. At this time GitLab does not
-take care of content replication in object storage.
+To have:
+
+- GitLab manage replication, follow [Enabling GitLab replication](#enabling-gitlab-managed-object-storage-replication).
+- Third-party services manage replication, follow [Third-party replication services](#third-party-replication-services).
+
+## Enabling GitLab managed object storage replication
+
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/10586) in GitLab 12.4.
+
+**Secondary** nodes can replicate files stored on the **primary** node regardless of
+whether they are stored on the local filesystem or in object storage.
+
+To enable GitLab replication, you must:
+
+1. Go to **Admin Area > Geo**.
+1. Press **Edit** on the **secondary** node.
+1. Enable the **Allow this secondary node to replicate content on Object Storage**
+   checkbox.
 
 For LFS, follow the documentation to
 [set up LFS object storage](../../../workflow/lfs/lfs_administration.md#storing-lfs-objects-in-remote-object-storage).
@@ -20,12 +34,21 @@ For CI job artifacts, there is similar documentation to configure
 
 For user uploads, there is similar documentation to configure [upload object storage](../../uploads.md#using-object-storage-core-only)
 
-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. **Secondary** nodes will automatically notice that the migrated
-files are now in object storage.
+If you want to migrate the **primary** node's files to object storage, you can
+configure the **secondary** in a few ways:
+
+- Use the exact same object storage.
+- Use a separate object store but leverage your object storage solution's built-in
+  replication.
+- Use a separate object store and enable the **Allow this secondary node to replicate
+  content on Object Storage** setting.
+
+GitLab does not currently support the case where both:
+
+- The **primary** node uses local storage.
+- A **secondary** node uses object storage.
 
-## Replication
+## Third-party replication services
 
 When using Amazon S3, you can use
 [CRR](https://docs.aws.amazon.com/AmazonS3/latest/dev/crr.html) to