(DOCSP-30104): Tutorial for modifying a shard zone (#7361) (#7367)

* (DOCSP-30104): Tutorial for modifying a shard zone

* move file to correct location

* remove duplicate toc entries

* change learn more links

* intro tweak

* fix code formatting

* remove monospace from step titles

* remove punctuation from step

* remove punctuation from step

* fix step formatting

* review feedback

* change syntax highlighting

* remove syntax highlighting

Author: jeff-allen-mongo

snooty.toml

@@ -224,6 +224,7 @@ toc_landing_pages = [
    "/storage",
    "/text-search",
    "/tutorial/insert-documents",
+   "/tutorial/manage-shard-zone",
    "/tutorial/install-mongodb-enterprise-on-amazon",
    "/tutorial/install-mongodb-enterprise-on-debian",
    "/tutorial/install-mongodb-enterprise-on-os-x",

source/data-center-awareness.txt

@@ -55,5 +55,3 @@ Further Reading
    :hidden:
 
    /core/workload-isolation
-   /core/zone-sharding
-   /tutorial/manage-shard-zone

source/tutorial/manage-shard-zone.txt

@@ -123,3 +123,8 @@ return any range associated to the ``NYC`` zone.
 
    use config
    db.tags.find({ tag: "NYC" })
+
+.. toctree::
+   :hidden:
+
+   /tutorial/manage-shard-zone/update-existing-shard-zone

source/tutorial/manage-shard-zone/update-existing-shard-zone.txt

@@ -0,0 +1,106 @@
+.. _sharding-update-existing-zone:
+
+=============================
+Update an Existing Shard Zone
+=============================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+.. facet::
+   :name: genre 
+   :values: tutorial
+
+After you specify a range of values for a shard zone, you can update the
+shard zone range if your application's requirements change.
+
+To update an existing shard zone, perform these steps:
+
+#. Stop the :term:`balancer`.
+
+#. Remove the old range from the zone.
+
+#. Update the zone's range.
+
+#. Restart the balancer.
+
+About this Task
+---------------
+
+- Zone ranges are inclusive of the lower boundary and exclusive of the
+  upper boundary.
+
+- After you modify a zone, the balancer must migrate chunks to the
+  appropriate zones based on the new range of values. Until balancing
+  completes, some chunks may reside on the wrong shard given the
+  configured zones for the sharded cluster.
+
+Before you Begin
+----------------
+
+To complete this tutorial, you must :ref:`deploy a sharded cluster
+<sharding-procedure-setup>` with a sharded collection and create a zone
+to modify.
+
+This example uses a sharded collection named ``users`` in the
+``records`` database, sharded by the ``zipcode`` field. 
+
+.. procedure::
+   :style: normal
+
+   .. step:: Add a shard to a zone called NYC
+
+      .. code-block:: none
+
+         sh.addShardToZone(<shard name>, "NYC")
+
+   .. step:: Specify a range of zipcode values for the NYC zone
+
+      .. code-block:: javascript
+
+         sh.updateZoneKeyRange("records.users", { zipcode: "10001" }, { zipcode: "10281" }, "NYC" )
+
+Steps
+-----
+
+The following procedure modifies the range of ``zipcode`` values for the
+``NYC`` zone to be ``11201`` through ``11240``.
+
+.. procedure::
+   :style: normal
+
+   .. step:: Stop the balancer
+
+      .. code-block:: javascript
+
+         sh.stopBalancer()
+
+   .. step:: Remove the current NYC range from the zone
+
+     .. code-block:: javascript
+
+         sh.removeRangeFromZone("records.user", { zipcode: "10001" }, { zipcode: "10281" } )
+         
+   .. step:: Update the zone key range for the NYC zone
+
+      .. code-block:: javascript
+
+         sh.updateZoneKeyRange("records.users", { zipcode: "11201" }, { zipcode: "11240" }, "NYC" )
+      
+   .. step:: Restart the balancer
+
+      .. code-block:: javascript
+
+         sh.startBalancer()
+
+Learn More
+----------
+
+- :method:`sh.removeRangeFromZone()`
+
+- :method:`sh.updateZoneKeyRange()`
+
+- :ref:`workload-isolation`