DOCS-5629 DOCS-5329 include archiveMovedChunks behavior in the chunk migration

Author: kay-kim

source/core/sharding-balancing.txt

@@ -45,7 +45,10 @@ To address uneven chunk distribution for a sharded collection, the
 balancer :doc:`migrates chunks </core/sharding-chunk-migration>` from
 shards with more chunks to shards with a fewer number of chunks. The
 balancer migrates the chunks, one at a time, until there is an even
-dispersion of chunks for the collection across the shards.
+dispersion of chunks for the collection across the shards. For details
+about chunk migration, see :ref:`chunk-migration-procedure`.
+
+.. include:: /includes/fact-archiveMovedChunks.rst
 
 Chunk migrations carry some overhead in terms of bandwidth and
 workload, both of which can impact database performance. The

source/core/sharding-chunk-migration.txt

@@ -30,6 +30,11 @@ either:
   a sharded collection's chunks across the shards. See :ref:`Migration
   Thresholds <sharding-migration-thresholds>` for more details.
 
+.. _chunk-migration-procedure:
+
+Chunk Migration Procedure
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
 All chunk migrations use the following procedure:
 
 #. The balancer process sends the :dbcommand:`moveChunk` command to
@@ -58,6 +63,11 @@ All chunk migrations use the following procedure:
    and once there are no open cursors on the chunk, the source shard
    deletes its copy of the documents.
 
+   .. versionchanged:: 2.6
+      
+      The source shard automatically archives the migrated documents by
+      default. For more information, see :ref:`moveChunk-directory`.
+
    .. versionchanged:: 2.4
 
       If the balancer needs to perform additional chunk migrations
@@ -133,6 +143,17 @@ the chunk migration have the following replication policy:
    Throttle in the v2.2 Manual
    </tutorial/configure-sharded-cluster-balancer/#sharded-cluster-config-secondary-throttle>`
 
+.. _moveChunk-directory:
+
+``moveChunk`` directory
+-----------------------
+
+Starting in MongoDB 2.6, :setting:`sharding.archiveMovedChunks` is
+enabled by default. With :setting:`sharding.archiveMovedChunks`
+enabled, the source shard archives the documents in the migrated chunks
+in a directory named after the collection namespace under the
+``moveChunk`` directory in the :setting:`storage.dbPath`.
+
 .. _jumbo-chunks:
 
 Jumbo Chunks

source/includes/fact-adding-shards-changes-cluster-balance.rst

@@ -3,3 +3,5 @@ When you add a shard to a sharded cluster, you affect the balance of
 collections. The balancer will begin migrating chunks so that the
 cluster will achieve balance. See :doc:`/core/sharding-balancing` for
 more information.
+
+.. include:: /includes/fact-archiveMovedChunks.rst

source/includes/fact-archiveMovedChunks.rst

@@ -0,0 +1,5 @@
+.. versionchanged:: 2.6
+
+   Chunk migrations can have an impact on disk space. Starting in
+   MongoDB 2.6, the source shard automatically archives the migrated
+   documents by default. For details, see :ref:`moveChunk-directory`.

source/includes/options-conf.yaml

@@ -940,10 +940,10 @@ description: |
 
   .. versionchanged:: 2.6 {{role}} is now the default behavior of MongoDB.
 
-  When true, the {{role}} option forces the :program:`mongod` instances to save
-  all documents migrated from this shard during chunk migrations to the
-  ``moveChunk`` directory of the :setting:`storage.dbPath`. MongoDB does not
-  delete data stored in ``moveChunk``.
+  When {{role}} is ``true``, the :program:`mongod` instance saves all
+  documents migrated from the shard to the ``moveChunk`` directory of
+  the :setting:`storage.dbPath`. MongoDB does not delete data stored in
+  ``moveChunk``.
 ---
 program: conf
 name: auditLog.destination