data center awareness documentation

source/administration/operational-segregation.txt

@@ -2,8 +2,6 @@
 Location and Operational Segregation in MongoDB Operations and Deployments
 ==========================================================================
 
-.. rename this file /administration/operational-segregation.txt
-
 .. default-domain:: mongodb
 
 Operational Overview
@@ -33,7 +31,7 @@ Specifically, with MongoDB, you can:
 - ensure that specific members of a replica set respond to queries.
 
 - ensure that specific ranges of your :term:`shard key` balance onto and
-  reside on specific :term:`shards`.
+  reside on specific :term:`shard`.
 
 - combine the above features in a single distributed deployment, on a
   per-operation (for read and write operations) and collection (for
@@ -65,19 +63,21 @@ documentation in the MongoDB Manual:
    Before adding operational segregation features to your application
    and MongoDB deployment, become familiar with all documentation of
    :doc:`replication </replication>` and :doc:`sharding </sharding>`,
-   particularly :doc:`/core/replication` and :doc:`/core/sharding`.
+   particularly :doc:`/core/replication` and :doc:`/core/sharded-clusters`.
+
+.. TODO uncomment this section when we can write content for it:
 
-Examples of Operational Segregation
------------------------------------
+   Examples of Operational Segregation
+   -----------------------------------
 
-Increase Data Locality in Geographically Distributed Cluster
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+   Increase Data Locality in Geographically Distributed Cluster
+   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Functional Segregation for Reporting and Backups
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+   Functional Segregation for Reporting and Backups
+   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Increase Read Locality for Distributed Applications
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+   Increase Read Locality for Distributed Applications
+   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Ensure Geographical Redundancy for Write Operations
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+   Ensure Geographical Redundancy for Write Operations
+   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

source/administration/tag-aware-sharding.txt

@@ -22,29 +22,149 @@ cluster. This capability enables the following deployment patterns:
 This document describes the behavior, operation, and use of tag aware
 sharding in MongoDB deployments.
 
+.. note::
+
+   Shard key tags are entirely distinct from :ref:`replica set member
+   tags <replica-set-read-preference-tag-sets>`.
+
 Behavior and Operations
 -----------------------
 
-- tags are cluster metadata. (implications.) Shell helpers to set the
-  metadata. The balancer does the rest.
+Tags in a shareded cluster are pieces of metadata that dictate the
+policy and behavior of the cluster balancer :term:`balancer`. Using
+tags, you may associate individual shards in a cluster with one or
+more strings, or tags. Then, you can assign this tag string to a range
+of :term:`shard key` values for a sharded collection. When migrating a
+chunk, the balancer will select a destination shard based on the
+configured tag ranges.
+
+To migrate chunks in a tagged environment, the balancer selects a
+target shard with a tag range that has an *upper* bound that *greater
+than* the migrating chunk's *lower* bound. If a shard with a matching
+tagged range exists, the balancer will migrate the chunk to that
+shard.
+
+.. note:: The balancer may migrate chunks to tagged shards that
+   contain values that exceed the upper bound of the selected tag
+   range.
+
+.. example::
 
-- tags are arbitrary. tags are independent of replica-set member
-  tags.
+   Given a sharded collection with two configured tag ranges, such
+   that:
 
-- tags only dictate balancing policy, and depending on chunk splits,
-  and current distribution of data it may take time for the cluster to
-  achieve desired distribution
+   - :term:`Shard key` values between ``100`` and ``200`` have tags to
+     direct corresponding chunks on shards tagged ``NYC``.
 
-- (more?)
+   - Shard Key values between ``200`` and ``300`` have tags to direct
+     corresponding chunks on shards tagged ``SFO``.
+
+   In this cluster, the balancer will migrate a chunk with shard key
+   values ranging between ``150`` and ``220`` to a shard tagged
+   ``NYC``, since ``150`` is closer to ``200`` than ``300``.
+
+After configuring sharding tags, the cluster may take some time to
+reach the proper distribution of data, depending on the division of
+chunks (i.e. splits) and the current distribution of data in the
+cluster. Once configured, the balancer will respect tag ranges during
+future :ref:`balancing rounds <sharding-internals-balancing>`.
 
 Administer Shard Tags
 ---------------------
 
+Associate tags with a particular shard using the
+:method:`sh.addShardTag()` method when connected to a
+:program:`mongos` instance. A single shard may have multiple tags, and
+multiple shards may also have the same tag.
+
+.. example::
+
+   The following example adds the tag ``NYC`` to two shards, and the tags
+   ``SFO`` and ``NRT`` to a third shard:
+
+   .. code-block:: javascript
+
+      sh.addShardTag("shard0000", "NYC")
+      sh.addShardTag("shard0001", "NYC")
+      sh.addShardTag("shard0002", "SFO")
+      sh.addShardTag("shard0002", "NRT")
+
+You may remove tags from a particular shard using the
+:method:`sh.removeShardTag()` method when connected to a
+:program:`mongos` instance, as in the following example, which removes
+the ``NRT`` tag from a shard:
+
+.. code-block:: javascript
+
+   sh.removeShardTag("shard0002", "NRT")
+
 Tag a Shard Key Range
 ~~~~~~~~~~~~~~~~~~~~~
 
+To assign a range of shard key values to a tag, use the
+:method:`sh.addTagRange()` method when connected to a
+:program:`mongos` instance. Any given shard key range may only have
+*one* assigned tag. However, you may assign the same tag to multiple
+shard key rage.
+
+.. example::
+
+   Given a collection named ``users`` in the ``records`` database,
+   sharded by the ``zipcode`` field. The following operations assign:
+
+   - two ranges of zip codes in Manhattan and Brooklyn the ``NYC`` tag
+
+   - one range of zip codes in San Francisco the ``SFO`` tag
+
+   .. code-block:: javascript
+
+      sh.addTagRange("records.users", { zipcode: "10001" }, { zipcode: "10281" }, "NYC")
+      sh.addTagRange("records.users", { zipcode: "11201" }, { zipcode: "11240" }, "NYC")
+      sh.addTagRange("records.users", { zipcode: "94102" }, { zipcode: "94135" }, "SFO")
+
 Remove a Tag From a Shard Key Range
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+The :program:`mongod` does not provide a helper for removing a tag
+rage. You may delete tag assignment from a shard key range by removing
+the corresponding document from the :data:`~config.tags` collection of
+the ``config`` database.
+
+Each document in the :data:`~config.tags` holds the :term:`namespace`
+of the sharded collection and a minimum shard key value.
+
+.. example::
+
+   The following example removes the ``NYC`` tag assignment for the
+   range of zip codes within Manhattan:
+
+   .. code-block:: javascript
+
+      use config
+      db.tags.remove({ _id: { ns: "records.users", min: { zipcode: "10001" }}, tag: "NYC" })
+
 View Existing Shard Tags
 ~~~~~~~~~~~~~~~~~~~~~~~~
+
+The output from :method:`sh.status()` lists tags associated with a
+shard, if any, for each shard. A shard's tags exist in the shard's
+document in the :data:`~config.shards` collection of the ``config``
+database. To return all shards with a specific tag use a sequence of
+operations that resemble the following, which will return only those
+shards tagged with ``NYC``:
+
+.. code-block:: javascript
+
+   use config
+   db.shards.find({ tags: "NYC" })
+
+You can find tag ranges for all :term:`namespaces <namespace>` in the
+:data:`~config.tags` collection of the ``config`` database. The output
+of :method:`sh.status()` displays all tag ranges. To return all shard
+key ranges tagged with ``NYC`` issue the following sequence of
+commands:
+
+.. code-block:: javascript
+
+   use config
+   db.shards.find({ tags: "NYC" })