DOCSP-46644: Stop balancer on a per-collection basis (#670)

* commit

* small

* feedback

* error

* feedback

* feedback and restructure

* tweaks

* little tweak

* feedback

* remove step

* feedback

Author: mayaraman19

source/includes/fact-mongosync-balancer.rst

@@ -1,7 +1,31 @@
 .. important::
 
-   When the source or destination cluster is a sharded cluster, you must stop 
-   the balancer on both clusters and not run the :dbcommand:`moveChunk` or
-   :dbcommand:`moveRange` commands for the duration of the migration. To stop 
-   the balancer, run the :dbcommand:`balancerStop` command and wait for the 
-   command to complete.
+   You must always disable the balancer on a sharded destination
+   cluster by using :dbcommand:`balancerStop`. 
+   After stopping the balancer, wait **fifteen minutes** before
+   starting ``mongosync``. This gives the cluster time to
+   finish any in-progress chunk migrations.
+
+   If the source or destination cluster is a sharded cluster
+   and you are not running ``mongosync`` with :ref:`namespace
+   filtering <c2c-filtered-sync>`,
+   you must disable the source cluster's balancer
+   by running the :dbcommand:`balancerStop` command and waiting 15 minutes
+   for the command to complete.
+
+   If the source or destination cluster is a sharded cluster and you
+   are running ``mongosync`` with namespace filtering, you can 
+   globally enable the source cluster's
+   balancer but you must disable it for 
+   all collections within the namespace filter. 
+   See :ref:`disabling-balancer-filtered`. You can also fully disable
+   the source cluster's balancer.
+
+   During migration, do not run the :dbcommand:`moveChunk` or 
+   :dbcommand:`moveRange` commands. If you have enabled the source cluster's
+   balancer, but disabled it for collections within the namespace
+   filter, do not run :dbcommand:`shardCollection` on collections
+   within the namespace filter. If you run :dbcommand:`shardCollection` on 
+   collections within the namespace filter during the migration, ``mongosync``
+   returns an error and stops, which requires you to start the migration
+   from scratch.

source/reference/limitations.txt

@@ -124,16 +124,31 @@ Sharded Clusters
      To check for index inconsistencies, see :ref:`Find Inconsistent
      Indexes Across Shards <manage-indexes-find-inconsistent-indexes>`.
 
-- You must stop the balancer on sharded source and destination clusters
-  for the entire lifetime of a migration. To stop the balancer, run the
-  :dbcommand:`balancerStop` command and wait for the command to
-  complete.
-
-  .. note::
-
-     After stopping the balancer, wait fifteen minutes before
-     starting ``mongosync``. This gives the cluster time to
-     finish any in progress chunk migrations.
+- If the source or destination cluster is a sharded cluster
+  and you are not running ``mongosync`` with :ref:`namespace
+  filtering <c2c-filtered-sync>`,
+  you must disable the source cluster's balancer
+  by running the :dbcommand:`balancerStop` command and waiting 15 minutes
+  for the command to complete.
+
+  If the source or destination cluster is a sharded cluster and you
+  are running ``mongosync`` with namespace filtering, you can 
+  globally enable the source cluster's
+  balancer but you must disable it for 
+  all collections within the namespace filter. 
+  See :ref:`disabling-balancer-filtered`. You can also fully disable
+  the source cluster's balancer.
+
+  You must always disable the balancer on a sharded destination
+  cluster by using :dbcommand:`balancerStop`.
+
+- If you have enabled the source cluster's
+  balancer, but disabled it for collections within the namespace
+  filter, do not run :dbcommand:`shardCollection` on collections
+  within the namespace filter. If you run :dbcommand:`shardCollection` on 
+  collections within the namespace filter during the migration, ``mongosync``
+  returns an error and stops, which requires you to start the migration
+  from scratch.
 
 - You must not run the :dbcommand:`moveChunk` and
   :dbcommand:`moveRange` commands on the source or destination clusters.

source/reference/mongosync/mongosync-behavior.txt

@@ -102,6 +102,49 @@ preserve the source cluster's sharding configuration.
 
 .. include:: /includes/fact-mongosync-balancer.rst
 
+.. _disabling-balancer-filtered:
+
+Disabling Balancer for Collections in Filtered Sync
+'''''''''''''''''''''''''''''''''''''''''''''''''''
+
+If you are using a :ref:`namespace filter <c2c-filtered-sync>`
+and want to enable your source cluster's balancer for 
+collections outside the namespace filter,
+follow these instructions before
+you start ``mongosync``.
+
+.. procedure::
+   :style: normal
+
+   .. step:: Enable the balancer for the source cluster.
+    
+      Before starting ``mongosync`` with a :ref:`namespace filter 
+      <c2c-filtered-sync>`, enable the balancer for the source cluster
+      by running the :method:`sh.startBalancer()` method in ``mongosh``.
+
+   .. step:: Disable the balancer for each collection.
+      
+      Disable the balancer for each collection within the
+      namespace filter by running the :dbcommand:`setAllowMigrations` command:
+
+      .. code-block:: javascript
+        
+        db.adminCommand(
+          { 
+            setAllowMigrations: “<db>.<collection>”,
+            allowMigrations: false
+          }
+        )
+
+      Run the preceding command for every collection within the
+      namespace filter.
+
+.. important:: 
+
+   If you enable the source cluster's balancer but do not use a
+   namespace filter, or if you do not disable the balancer for all
+   collections within the namespace filter, ``mongosync`` fails.
+
 Pre-Split Chunks
 ''''''''''''''''
 
@@ -131,7 +174,7 @@ primary shard to each database by means of a round-robin.
 
 .. warning::
 
-   Running :dbcommand:`movePrimary` on the source or desintation cluster
+   Running :dbcommand:`movePrimary` on the source or destination cluster
    during migration may result in a fatal error or require you to
    restart the migration from the start. For more information, see
    :ref:`c2c-sharded-limitations`.