DOCS-16527 replica set to sharded cluster page (#363) (#373)

sonderdonk-mdb · web-flow · commit ac92dd463e11 · 2024-08-06T10:14:41.000-04:00
* DOCSP-16527 * DOCS-16527 changed structure
diff --git a/snooty.toml b/snooty.toml
@@ -16,6 +16,7 @@ toc_landing_pages = ["/quickstart",
                      "/installation",
                      "reference/reference",
                      "/connecting",
+                     "/topologies",
                      "/using-mongosync",
                      "/multiple-mongosyncs",
                      "/release-notes/release-notes",
diff --git a/source/faq.txt b/source/faq.txt
@@ -104,6 +104,8 @@ when ``mongosync`` became unavailable.
 
 .. include:: /includes/fact-restart-resume-delay.rst
 
+.. _c2c-faq-arbiters:
+
 Can the source or destination be a replica set with arbiters? 
 -------------------------------------------------------------
 
diff --git a/source/includes/example-connection-string-general.rst b/source/includes/example-connection-string-general.rst
@@ -0,0 +1,5 @@
+.. code-block:: shell
+
+   mongosync \
+         --cluster0 "<cluster0_connection_string>" \
+         --cluster1 "<cluster1_connection_string>"
diff --git a/source/includes/limitations-rs-to-sharded.rst b/source/includes/limitations-rs-to-sharded.rst
@@ -0,0 +1,10 @@
+- ``mongosync`` allows users to rename collections that the
+  ``sharding.shardingEntries`` option includes during sync with some 
+  limitations. For details, see 
+  :ref:`Renaming During Sync <rename-during-sync>`.
+- If you use the ``sharding.createSupportingIndexes`` option, the indexes are 
+  automatically created on the destination cluster during the sync. You cannot 
+  create these indexes afterwards on the source cluster.
+- If you want to create an index to support shard keys manually, you 
+  must create the index before ``mongosync`` starts or after the migration is 
+  complete and ``mongosync`` has stopped.
diff --git a/source/index.txt b/source/index.txt
@@ -40,7 +40,7 @@ common questions users have asked about ``mongosync``.
    /about-mongosync
    /installation
    /connecting
-   /multiple-mongosyncs
+   /topologies
    /reference
    /release-notes
    /faq
diff --git a/source/quickstart.txt b/source/quickstart.txt
@@ -34,12 +34,14 @@ the rest of the {+c2c-product-name+} documentation.
 
 - The destination cluster must be the same version or up to two versions ahead
   of the source cluster. The patch version is not important, so long as they 
-  meets the minimum patch :ref:`version requirements
+  meet the minimum patch :ref:`version requirements
   <c2c-server-version-compatibility>`.
 
 Follow the instructions below to set up {+c2c-product-name+}, connect
 your clusters, and synchronize your data.
 
+.. _c2c-quickstart-setup:
+
 Setup
 -----
 
@@ -48,14 +50,18 @@ Setup
 
    .. step:: Define a source and a destination cluster
 
+      .. _c2c-quickstart-define-clusters:
+
       If you already have a MongoDB cluster, either self-managed or
       hosted in :atlas:`MongoDB Atlas </getting-started?jmp=docs>`, 
       use that cluster as the source cluster. If you don't have a
       cluster to work with, you will need to create one.
 
       This Quickstart works when the destination cluster and the source
-      cluster are both replica sets. To sync from a replica set to a
-      sharded cluster, or between sharded clusters, see:
+      cluster are both replica sets. 
+      
+      To sync from a replica set to a sharded cluster, see 
+      :ref:`c2c-rs-to-sharded`. To sync between sharded clusters, see
       :ref:`c2c-sharded-clusters`.
 
       .. seealso::
@@ -79,6 +85,8 @@ Setup
 
    .. step:: Define administrative users
 
+      .. _c2c-quickstart-define-users:
+
       If either cluster is hosted in Atlas, or if either of them
       requires authentication, you must create a database user that has
       permissions in both clusters. 
@@ -116,6 +124,8 @@ Setup
 
    .. step:: Download and install ``mongosync``
 
+      .. _c2c-quickstart-download:
+
       ``mongosync`` is the tool that connects the source and
       destination clusters. You can host ``mongosync`` on its own
       hardware, ``mongosync`` does not have to run on the hardware that
@@ -168,6 +178,8 @@ Connect the Clusters
 
    .. step:: Initialize mongosync
 
+      .. _c2c-initialize:
+      
       ``mongosync`` must create an initial connection to the source and
       destination clusters before it can start to sync data. To create the initial
       connection, issue the following command with your connection
diff --git a/source/reference/api/start.txt b/source/reference/api/start.txt
@@ -361,6 +361,7 @@ following configurations:
 
 * Sync between sharded clusters that differ in the number of shards.
 
+.. _c2c-shard-replica-sets:
 
 Shard Replica Sets 
 ~~~~~~~~~~~~~~~~~~
@@ -371,7 +372,7 @@ Sync from a replica set to a sharded cluster requires the
 ``sharding`` option. This option configures how ``mongosync`` shards
 collections.
 
-The ``sharding.shardEntries`` array specifies the collections to shard.
+The ``sharding.shardingEntries`` array specifies the collections to shard.
 Collections that are not listed in this array replicate as unsharded.
 
 Supporting Indexes
@@ -389,7 +390,7 @@ This is done by setting the ``sharding.createSupportingIndexes`` option.
 
 When ``sharding.createSupportingIndexes`` is ``false`` (the default): 
 
-* Each shard key you provide for the ``sharding.shardEntries`` option
+* Each shard key you provide for the ``sharding.shardingEntries`` option
   must have an existing index on the source cluster.
 
 * One of the indexes used for the shard key must have simple collation if the 
@@ -422,7 +423,7 @@ Rename During Sync
 
 .. versionadded:: 1.1
 
-Collections listed in the ``sharding.shardEntries`` array 
+Collections listed in the ``sharding.shardingEntries`` array 
 when synced from a replica set to a sharded cluster 
 become sharded collections on the destination cluster.
 
diff --git a/source/reference/limitations.txt b/source/reference/limitations.txt
@@ -87,20 +87,8 @@ Sharded Clusters
 - Sync from a replica set to a sharded cluster has the following
   limitations:
 
-  - ``mongosync`` allows users to rename collections that the
-    ``sharding.shardingEntries`` option for the :ref:`c2c-api-start`
-    command includes during sync. To see limitations on renaming
-    collections while ``mongosync`` is running, see :ref:`Renaming
-    During Sync <rename-during-sync>`.
-  - When using the ``sharding.createSupportingIndexes`` option to create
-    indexes supporting shard keys on the destination cluster during
-    sync, you cannot create these indexes afterwards on the source
-    cluster.
-
-    The index must either exist before ``mongosync`` starts or be
-    created after the migration is complete and ``mongosync`` has
-    stopped.
-
+  .. include:: /includes/limitations-rs-to-sharded.rst
+    
 - Within a collection, the ``_id`` field must be unique across all of
   the shards in the cluster. See :ref:`sharded-clusters-unique-indexes`
   for more details.
diff --git a/source/reference/mongosync.txt b/source/reference/mongosync.txt
@@ -62,11 +62,7 @@ The ``mongosync`` command layout below is modified for display. To
 connect ``cluster0`` to ``cluster1`` with ``mongosync``, enter the
 following command on one line:
 
-.. code-block:: shell
-
-   mongosync \
-         --cluster0 "<cluster0_connection_string>" \
-         --cluster1 "<cluster1_connection_string>"
+.. include:: /includes/example-connection-string-general.rst
 
 For more information on how to format your connection strings, see 
 :ref:`c2c-connecting`.
diff --git a/source/topologies.txt b/source/topologies.txt
@@ -0,0 +1,46 @@
+============================
+Supported Cluster Topologies
+============================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+  
+Cluster topology affects how nodes are arranged within a cluster. Topology 
+impacts the availability and performance of your MongoDB deployment. 
+
+The topology you choose can affect how ``mongosync`` synchronizes data between 
+clusters.
+
+Requirements
+------------
+
+:ref:`c2c-mongosync` supports two cluster topologies: 
+
+- :ref:`Replica sets <replication>`
+
+- :ref:`Sharded clusters <sharded-cluster>`
+
+If you are syncing a sharded cluster to another sharded cluster, they are not 
+required to have the same number of shards.
+
+``mongosync`` doesn't support sync from a sharded cluster to a replica set.
+
+Get Started
+-----------
+
+- To sync a replica set to a replica set, see the 
+  :ref:`Quick Start Guide <c2c-quickstart>`.
+
+- To sync a replica set to a sharded cluster, see :ref:`c2c-rs-to-sharded`.
+
+- To sync a sharded cluster to another sharded cluster, see 
+  :ref:`c2c-sharded-clusters`.
+
+.. toctree::
+   :titlesonly:
+
+   topologies/rs-to-sharded
+   topologies/multiple-mongosyncs
diff --git a/source/topologies/multiple-mongosyncs.txt b/source/topologies/multiple-mongosyncs.txt
@@ -1,8 +1,8 @@
 .. _c2c-sharded-clusters:
 
-=====================================
-Use ``mongosync`` on Sharded Clusters
-=====================================
+=====================
+Sync Sharded Clusters
+=====================
 
 .. default-domain:: mongodb
 
diff --git a/source/topologies/rs-to-sharded.txt b/source/topologies/rs-to-sharded.txt
@@ -0,0 +1,116 @@
+.. _c2c-rs-to-sharded:
+
+=======================================
+Sync a Replica Set to a Sharded Cluster
+=======================================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: twocols
+
+This page outlines the procedure to synchronize data from a replica set to a 
+sharded cluster using :program:`mongosync`. 
+
+.. note::
+
+   ``mongosync`` doesn't support syncing from a sharded cluster to a replica 
+   set.
+
+
+Before You Begin
+----------------
+
+- :ref:`Define <c2c-quickstart-define-clusters>` your source replica set and 
+  destination sharded cluster.
+
+- :ref:`Define <c2c-quickstart-define-users>` an administrative user that has 
+  permissions in both clusters.
+
+- :ref:`Download and install <c2c-quickstart-download>` ``mongosync``.
+
+To learn more, see the :ref:`mongosync setup <c2c-quickstart-setup>` 
+instructions.
+
+Steps 
+-----
+
+.. procedure::
+   :style: normal
+
+   .. step:: Connect the replica set and sharded cluster
+
+      ``mongosync`` must create an initial connection between the source 
+      replica set and the destination sharded cluster before you can start to 
+      sync data. 
+
+      To connect ``cluster0`` to ``cluster1`` with ``mongosync``, enter the
+      following command:
+
+      .. include:: /includes/example-connection-string-general.rst
+
+      Follow the :ref:`connection instructions <c2c-conn-top-level>` 
+      for your cluster architecture to format your connection strings and 
+      connect to the :binary:`mongos` instance in your cluster. 
+
+   .. step:: Start synchronization
+
+       Call the :ref:`start <c2c-api-start>` endpoint to initiate data 
+       synchronization. 
+       
+       To sync from a replica set to a sharded cluster, set the 
+       ``sharding`` option for the ``start`` command to shard collections on 
+       the destination cluster. For more information, see 
+       :ref:`Sharding Parameters <c2c-api-start-sharding>`.
+
+       Use the ``sharding.shardingEntries`` parameter to specify the collections 
+       to shard. Collections that you do not list in this array replicate as 
+       unsharded. For more information, see 
+       :ref:`Shard Replica Sets <c2c-shard-replica-sets>` and 
+       :ref:`sharding-shard-key-selection`.
+
+       The following example starts a sync from a replica set to a sharded
+       cluster: 
+
+       Request
+       ~~~~~~~
+
+       .. literalinclude:: /includes/api/requests/start-rs-shard.sh
+
+       Response
+       ~~~~~~~~
+
+       .. literalinclude:: /includes/api/responses/success.json
+          :language: json
+          :copyable: false
+
+Next Steps
+----------
+
+You can finalize a migration and transfer your application workload from the 
+source to the destination cluster using the ``mongosync`` cutover process.
+
+Limitations
+-----------
+
+- You cannot use the :ref:`reverse <c2c-api-reverse>` endpoint between a 
+  replica set and a sharded cluster. 
+
+.. include:: /includes/limitations-rs-to-sharded.rst
+
+- If the source replica set has :ref:`arbiters <c2c-faq-arbiters>`, the source 
+  replica set must have more than 2 non-arbiter nodes and you must sync from a 
+  non-arbiter node. 
+
+For more details, see :ref:`c2c-limitations`.
+
+Learn More
+----------
+
+- :ref:`c2c-quickstart`
+- :ref:`Sync Sharded Clusters <c2c-sharded-clusters>`
+- :ref:`About mongosync <about-mongosync>`
+- :ref:`mongosync <c2c-mongosync>`
+- :ref:`mongosync States <c2c-states>`
+
