DOCSP-46644: Stop balancer on a per-collection basis

source/includes/fact-mongosync-balancer.rst

@@ -1,7 +1,16 @@
 .. 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.
+   the source cluster's balancer on collections within the :ref:`namespace
+   filter <c2c-filtered-sync>`. You can enable the source cluster's balancer on
+   the cluster level and for collections outside the namespace filter. 
+   You must also stop the destination 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,20 @@ 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.
+- When the source or destination cluster is a sharded cluster, you must stop 
+  the source cluster's balancer on collections within the :ref:`namespace
+  filter <c2c-filtered-sync>`. You can enable the source cluster's balancer on
+  the cluster level and for collections outside the namespace filter. 
+  If you are not running a filtered sync, you must stop the source cluster's
+  balancer.
+  You must also stop the destination cluster's balancer. See 
+  :ref:`enabling-balancer-filtered` to learn how to enable the balancer during
+  filtered sync.
+
+- 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.
 
 - 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,40 @@ preserve the source cluster's sharding configuration.
 
 .. include:: /includes/fact-mongosync-balancer.rst
 
+.. _enabling-balancer-filtered:
+
+Enabling Balancer in Filtered Sync
+''''''''''''''''''''''''''''''''''
+
+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``. 
+Then, disable the balancer for each collection within the
+namespace filter by running the :dbcommand:`setAllowMigrations` command:
+
+.. code-block:: shell
+
+   db.adminCommand(
+     { 
+       setAllowMigrations: “<db>.<collection>”,
+       allowMigrations: false
+     }
+   )
+
+Run the preceding command for every collection within the
+namespace filter.
+
+Then, run the :dbcommand:`balancerStop` command to stop
+the balancer on the destination cluster and wait for the command to complete.
+
+After stopping the balancer, wait fifteen minutes before
+starting ``mongosync``. This gives the cluster time to
+finish any in progress chunk migrations.
+
+If you enable the source cluster's balancer but do not use a
+namespace filter, or if you disable the balancer for all
+collections within the namespace filter, ``mongosync`` fails.
+
 Pre-Split Chunks
 ''''''''''''''''
 
@@ -131,7 +165,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`.