DOCS-298 DOCS-299 initial edits

Author: Bob Grabar

source/administration/sharding.txt

@@ -7,9 +7,7 @@ Shard Cluster Administration
 
 .. default-domain:: mongodb
 
-This document provides a collection of basic operations and procedures
-for administering :term:`shard clusters <shard cluster>`.
-
+This document describes common administrative tasks.
 For a full introduction to sharding in MongoDB see
 ":doc:`/core/sharding`," and for a complete overview of all sharding
 documentation in the MongoDB Manual, see ":doc:`/sharding`." The
@@ -19,35 +17,40 @@ cluster. Finally, the ":doc:`/core/sharding-internals`" document
 provides a more detailed introduction to sharding when troubleshooting
 issues or understanding your cluster's behavior.
 
+
 .. contents:: Sharding Procedures:
    :backlinks: none
    :local:
 
 .. _sharding-procedure-setup:
 
-Setup
------
+Set up a Shard Cluster
+----------------------
+
+Before deploying a shard cluster, see the requirements listed in
+:ref:`Requirements for Shard Clusters <sharding-requirements>`.
+
+For testing purposes, you can run all the required shard processes on a
+single server. For production, use the configurations described in
+:doc:`/administration/replication-architectures`.
 
-If you have an existing replica set, you can use the
-":doc:`/tutorial/convert-replica-set-to-replicated-shard-cluster`"
-tutorial as a guide. If you're deploying a :term:`shard cluster` from
-scratch, see the ":doc:`/tutorial/deploy-shard-cluster`" tutorial for
-more detail or use the following procedure as a quick starting point:
+.. include:: /includes/warning-sharding-hostnames.rst
 
-#. Provision the required hardware.
+.. TODO Keep this or delete it:
+   If you have an existing replica set, you can use the
+   :doc:`/tutorial/convert-replica-set-to-replicated-shard-cluster`
+   tutorial as a guide. If you're deploying a :term:`shard cluster` from
+   scratch, see the :doc:`/tutorial/deploy-shard-cluster` tutorial for
+   more detail or use the following procedure as a quick starting point:
 
-   The ":ref:`sharding-requirements`" section describes what you'll
-   need to get started.
+1. Set up the required config servers, shards, and :program:`mongos`
+   instances described in :ref:`Sharding Infrastructure
+   <sharding-requirements-infrastructure>`.
 
-   .. warning:: Sharding and "localhost" Addresses
 
-      If you use either "localhost" or "``127.0.0.1``" as the host
-      identifier, then you must use "localhost" or "``127.0.0.1``" for
-      *all* host settings for any MongoDB instances in the cluster. If
-      you mix localhost addresses with remote host address, MongoDB will
-      produce errors.
+#. Start the three (3) config servers.
 
-#. On all three (3) config server instances, issue the following
+#. On all three config server instances, issue the following
    command to start the :program:`mongod` process:
 
    .. code-block:: sh
@@ -129,8 +132,8 @@ more detail or use the following procedure as a quick starting point:
 
          replicaSetName/<seed1>,<seed2>,<seed3>
 
-      For example, if the name of the replica set is "``repl0``", then
-      your :method:`sh.addShard` command would be:
+      For example, if the name of the replica set is ``repl0``, then
+      your :method:`sh.addShard()` command would be:
 
       .. code-block:: javascript
 
@@ -199,9 +202,9 @@ more detail or use the following procedure as a quick starting point:
    the distribution of data. Furthermore, you cannot change a
    collection's shard key once it has been set.
 
-   See the ":ref:`Shard Key Overview <sharding-shard-key>`" and the
-   more in depth documentation of ":ref:`Shard Key Qualities
-   <sharding-internals-shard-keys>`" to help you select better shard
+   See the :ref:`Shard Key Overview <sharding-shard-key>` and the
+   more in depth documentation of :ref:`Shard Key Qualities
+   <sharding-internals-shard-keys>` to help you select better shard
    keys.
 
    If you do not specify a shard key, MongoDB will shard the
@@ -271,7 +274,7 @@ procedure:
       following form: the replica set name, followed by a forward
       slash, followed by a comma-separated list of seeds for the
       replica set. For example, if the name of the replica set is
-      "myapp1", then your :method:`sh.addShard` command might resemble:
+      "myapp1", then your :method:`sh.addShard()` command might resemble:
 
       .. code-block:: javascript
 
@@ -282,9 +285,9 @@ procedure:
    It may take some time for :term:`chunks <chunk>` to migrate to the
    new shard.
 
-   See the ":ref:`Balancing and Distribution <sharding-balancing>`"
-   section for an overview of the balancing operation and the ":ref:`Balancing Internals
-   <sharding-balancing-internals>`" section for additional information.
+   See the :ref:`Balancing and Distribution <sharding-balancing>`
+   section for an overview of the balancing operation and the :ref:`Balancing Internals
+   <sharding-balancing-internals>` section for additional information.
 
 .. _sharding-procedure-remove-shard:
 
@@ -695,7 +698,7 @@ Balancer Operations
 This section provides an overview of common administrative procedures
 related to balancing and the balancing process.
 
-.. seealso:: ":ref:`sharding-balancing`" and the
+.. seealso:: :ref:`sharding-balancing` and the
    :dbcommand:`moveChunk` that provides manual :term:`chunk`
    migrations.
 
@@ -947,7 +950,7 @@ name.
 #. Shut down the config server that you're moving.
 
    This will render all config data for your cluster :ref:`read only
-   <sharding-config-server>`."
+   <sharding-config-server>`.
 
 #. Change the DNS entry that points to the system that provided the old
    config server, so that the *same* hostname points to the new
@@ -1072,7 +1075,7 @@ of the cluster metadata from the config database is straight forward:
 .. [#read-only] While one of the three config servers unavailable, no
    the cluster cannot split any chunks nor can it migrate chunks
    between shards. Your application will be able to write data to the
-   cluster. The ":ref:`sharding-config-server`" section of the
+   cluster. The :ref:`sharding-config-server` section of the
    documentation provides more information on this topic.
 
 .. index:: troubleshooting; sharding

source/core/sharding-internals.txt

@@ -495,3 +495,34 @@ All chunk migrations use the following procedure:
 When the ``_secondaryThrottle`` is ``true`` for :dbcommand:`moveChunk`
 or the :term:`balancer`, MongoDB ensure that *one* :term:`secondary`
 member has replicated changes before allowing new chunk migrations.
+
+Config Database
+---------------
+
+The ``config`` database contains sharding configuration information. To
+start the ``config`` database from the :program:`mongo` shell, issue the
+following command:
+
+.. code-block:: javascript
+
+   use config
+
+The config database includes the following collections used by sharding:
+
+- ``chunks``
+
+- ``databases``
+
+- ``lockpings``
+
+- ``locks``
+
+- ``mongos``
+
+- ``settings``
+
+- ``shards``
+
+- ``system.indexes``
+
+- ``version``

source/core/sharding.txt

@@ -154,9 +154,10 @@ A :term:`shard cluster` has the following components:
   configuration server process, but always use exactly three config
   servers for redundancy and safety in production.
 
-- Two or more :program:`mongod` instances, to hold data.
+- Two or more shards. Each shard consists of one or more :program:`mongod`
+  instances, which store the data for that shard.
 
-  These are "normal," :program:`mongod` instances that hold all of the
+  These "normal" :program:`mongod` instances hold all of the
   actual data for the cluster.
 
   Typically each shard is a :term:`replica sets <replica set>`. Each

source/includes/warning-sharding-hostnames.rst

@@ -0,0 +1,9 @@
+.. warning:: Sharding and "localhost" Addresses
+
+   If you use either "localhost" or ``127.0.0.1`` as the hostname
+   portion of any host identifier, for example as the ``host`` argument
+   to :dbcommand:`addShard` or the value to the :option:`mongos
+   --configdb` run time option, then you must use "localhost" or
+   ``127.0.0.1`` for *all* host settings for any MongoDB instances in
+   the cluster. If you mix localhost addresses and remote host address,
+   MongoDB will error.

source/tutorial/deploy-shard-cluster.txt

@@ -4,29 +4,18 @@ Deploy a Shard Cluster
 
 .. default-domain:: mongodb
 
-Synopsis
---------
-
 This document describes how to deploy a :term:`shard cluster` for a
-standalone :program:`mongod` instance.
-
-To deploy a shard cluster for an existing replica set, see
+standalone :program:`mongod` instance. To deploy a shard cluster for an
+existing replica set, see
 :doc:`/tutorial/convert-replica-set-to-replicated-shard-cluster`.
 
+Procedure
+---------
+
 Before deploying a shard cluster, see the requirements listed in
 :ref:`Requirements for Shard Clusters <sharding-requirements>`.
 
-.. warning:: Sharding and "localhost" Addresses
-
-   If you use either "localhost" or ``127.0.0.1`` as the hostname
-   portion of any host identifier, for example as the ``host`` argument to
-   :dbcommand:`addShard` or the value to the :option:`mongos --configdb`
-   run time option, then you must use "localhost" or ``127.0.0.1``
-   for *all* host settings. If you mix localhost addresses and remote
-   host address, MongoDB will error.
-
-Procedure
----------
+.. include:: /includes/warning-sharding-hostnames.rst
 
 Start Config Server Database Instances
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -132,7 +121,7 @@ These operations add two shards, provided by:
 - the replica set name and ``s1``, that includes the
   ``sfo40.example.net`` host.
 
-.. admonition:: All shards should be replica sets.
+.. admonition:: All shards should be replica sets
 
    .. versionchanged:: 2.0.3