merge: DOCS-865

Author: Sam Kleinman

source/administration/sharding.txt

@@ -96,8 +96,8 @@ use the following procedure as a quick starting point:
       sh.addShard( "<setName>/mongodb0.example.net:27027" )
 
    Replace, ``<setName>`` with the name of the replica set, and
-   MongoDB will discover all other members of the replica set. Repeat
-   this step for each new shard in your cluster.
+   MongoDB will discover all other members of the replica set.
+   Repeat this step for each new shard in your cluster.
 
    .. optional::
 
@@ -222,6 +222,8 @@ procedure:
 
    Replace ``<hostname>`` and ``<port>`` with the hostname and TCP
    port number of where the shard is accessible.
+   Alternately specify a :term:`replica set` name and at least one
+   hostname which is a member of the replica set.
 
    For example:
 

source/reference/command/addShard.txt

@@ -6,29 +6,65 @@ addShard
 
 .. dbcommand:: addShard
 
-   :option name: Optional. Unless specified, a name will be
-                 automatically provided to uniquely identify
-                 the shard.
+   :param string hostname: a hostname or replica-set/hostname string.
 
-   :option maxSize: Optional. Unless specified, shards will consume
-                    the total amount of available space on their
-                    machines if necessary. Use the ``maxSize`` value
-                    to limit the amount of space the database can
-                    use. Specify this value in megabytes.
+   :param string name: Optional. Unless specified, a name will be
+                       automatically provided to uniquely identify
+                       the shard.
 
-   The :dbcommand:`addShard` command registers a new with a sharded
-   cluster. You must run this command against a :program:`mongos`
-   instance. The command takes the following form:
+   :param integer maxSize: Optional. Unless specified, shards will consume
+                           the total amount of available space on their
+                           machines if necessary. Use the ``maxSize`` value
+                           to limit the amount of space the database can
+                           use. Specify this value in megabytes.
+
+   Use the :dbcommand:`addShard` command to add a database instance
+   or replica set to a :term:`sharded cluster`.
+   You must run this command against a :program:`mongos` instance.
+
+   The command takes the following form:
 
    .. code-block:: javascript
 
       { addShard: "<hostname>:<port>" }
 
+   .. example::
+
+      .. code-block:: javascript
+
+         db.runCommand({addShard: "mongodb0.example.net:27027"})
+
    Replace ``<hostname>:<port>`` with the hostname and port of the
-   database instance you want to add as a shard. Because the
-   :program:`mongos` instances do not have state and distribute
-   configuration in the :term:`config database`, send this
-   command to only one :program:`mongos` instance.
+   database instance you want to add as a shard.
+
+   .. warning::
+
+      Do not use ``localhost`` for the hostname unless your
+      :term:`configuration server <config database>`
+      is also running on ``localhost``.
+
+   The optimal configuration is to deploy shards across
+   :term:`replica sets <replica set>`.
+   To add a shard on a replica set you must specify the name of the
+   replica set and the hostname of at least one member of the replica
+   set.  You may specify all of the hostnames, but at least one member
+   must be specified.
+
+   .. code-block:: javascript
+
+      { addShard: "replica-set/hostname:port" }
+
+   .. example::
+
+      .. code-block:: javascript
+
+         db.runCommand({ addShard: "repl0/mongodb3.example.net:27327"})
+
+   If you specify additional hostnames, all must be members of the same
+   replica set.
+
+   Send this command to only one :program:`mongos` instance, it will
+   store shard configuration information in the :term:`config database`.
 
    .. note::
 
@@ -39,3 +75,10 @@ addShard
       The ``maxSize`` constraint prevents the :term:`balancer` from
       migrating chunks to the shard when the value of
       :status:`mem.mapped` exceeds the value of ``maxSize``.
+
+   .. seealso::
+
+      * :method:`sh.addShard()`
+      * :doc:`/administration/sharding`
+      * :doc:`/tutorial/add-shards-to-shard-cluster`
+      * :doc:`/tutorial/remove-shards-from-cluster`

source/reference/method/db.printShardingStatus.txt

@@ -9,4 +9,9 @@ db.printShardingStatus()
    Provides a formatted report of the sharding configuration and the
    information regarding existing chunks in a :term:`sharded cluster`.
 
-   .. seealso:: :method:`sh.status()`
+   This method must be executed on a :program:`mongos` instance.
+
+   This method is a wrapper around the :dbcommand:`printShardingStatus`
+   command.
+
+   .. seealso:: :method:`sh.status()`, :dbcommand:`printShardingStatus`

source/reference/method/sh.addShard.txt

@@ -6,22 +6,57 @@ sh.addShard()
 
 .. method:: sh.addShard(host)
 
-   :param host: Specify the hostname of a new shard server.
+   :param string host: Specify the hostname of a database instance or a
+                       replica set configuration.
 
-   Use this to add shard instances to the current :term:`cluster`. The
-   ``host`` parameter can be in any of the following forms: ::
+   Use this method to add a database instance or replica set to a
+   :term:`sharded cluster`.
+   This method must be run on a :program:`mongos` instance.
+   The ``host`` parameter can be in any of the following forms: ::
 
         [hostname]
         [hostname]:[port]
         [set]/[hostname]
         [set]/[hostname],[hostname]:port
 
    You can specify shards using the hostname, or a hostname and port
-   combination if the shard is running on a non-standard port. A
-   :term:`replica set` can also function as a shard member. In these
-   cases supply :method:`addShard <sh.addShard()>` with the set name,
-   followed by at least one existing member of the set as a seed in a
-   comma separated list, as in the final two examples.
-
-   This function provides a wrapper around the administrative command
-   :dbcommand:`addShard`.
+   combination if the shard is running on a non-standard port.
+
+   .. warning::
+
+      Do not use ``localhost`` for the hostname unless your
+      :term:`configuration server <config database>`
+      is also running on ``localhost``.
+
+   The optimal configuration is to deploy shards across
+   :term:`replica sets <replica set>`.
+   To add a shard on a replica set you must specify the name of the
+   replica set and the hostname of at least one member of the replica
+   set.  You may specify all of the hostnames, but at least one member
+   must be specified.
+
+   If you specify additional hostnames, all must be members of the same
+   replica set.
+
+   .. code-block:: javascript
+
+      sh.addShard("set-name/seed-hostname")
+
+   .. example::
+
+      .. code-block:: javascript
+
+         sh.addShard("repl0/mongodb3.example.net:27327")
+
+   The :method:`sh.addShard()` method is a helper for the
+   :dbcommand:`addShard` command.
+   The :dbcommand:`addShard` command has additional options which are
+   not available with this helper.
+
+   .. seealso::
+
+      * :dbcommand:`addShard`
+      * :doc:`/administration/sharding`
+      * :doc:`/tutorial/add-shards-to-shard-cluster`
+      * :doc:`/tutorial/remove-shards-from-cluster`
+

source/sharding.txt

@@ -7,19 +7,17 @@ Sharding
 Sharding distributes a
 single logical database system across a cluster of machines. Sharding
 uses range-based portioning to distribute :term:`documents <document>`
-based on a
-specific :term:`shard key`.
+based on a specific :term:`shard key`.
 
 This page lists the documents, tutorials, and reference pages that
 describe sharding.
 
 For an overview, see :doc:`/core/sharding`. To configure, maintain, and
-troubleshoot sharded clusters, see :doc:`/administration/sharding`. For
-deployment architectures, see
-:doc:`/administration/sharding-architectures`. For details on the
-internal operations of sharding, see :doc:`/core/sharding-internals`.
-For procedures for performing certain sharding tasks, see the :ref:`Tutorials <sharding-tutorials>`
-list.
+troubleshoot sharded clusters, see :doc:`/administration/sharding`.
+For deployment architectures, see :doc:`/administration/sharding-architectures`.
+For details on the internal operations of sharding, see :doc:`/core/sharding-internals`.
+For procedures for performing certain sharding tasks, see the
+:ref:`Tutorials <sharding-tutorials>` list.
 
 Documentation
 -------------

source/tutorial/add-shards-to-shard-cluster.txt

@@ -48,6 +48,12 @@ Or you can use the :method:`sh.addShard()` helper in the
 Replace ``[hostname]`` and ``[port]`` with the hostname and TCP
 port number of where the shard is accessible.
 
+.. warning::
+
+   Do not use ``localhost`` for the hostname unless your
+   :term:`configuration server <config database>`
+   is also running on ``localhost``.
+
 For example:
 
 .. code-block:: javascript

source/tutorial/deploy-shard-cluster.txt

@@ -74,7 +74,7 @@ The :program:`mongos` instance runs on the default MongoDB TCP port:
 
 To start :program:`mongos` instance running on the
 ``mongos0.example.net`` host, that connects to the config server
-instances running on the following hosts: 
+instances running on the following hosts:
 
 - ``mongoc0.example.net``
 - ``mongoc1.example.net``
@@ -112,18 +112,19 @@ port ``27017``, issue the following command:
 
    mongo mongos0.example.net
 
-Then, from the :program:`mongo` shell connected to the :program:`mongos`
+Then, from a :program:`mongo` shell connected to the :program:`mongos`
 instance, call the :method:`sh.addShard()` method for each shard that
 you want to add to the cluster:
 
 .. code-block:: javascript
 
-   sh.addShard( "sfo30.example.net" )
-   sh.addShard( "sfo40.example.net" )
+   sh.addShard( "s0/sfo30.example.net" )
+   sh.addShard( "s1/sfo40.example.net" )
 
-If ``sfo30.example.net`` and ``sfo40.example.net`` are members of a
-replica set, MongoDB will discover all other members of the replica
-set.
+If the host you are adding is a member of a replica set, you
+*must* specify the name of the replica set.  :program:`mongos`
+will discover the names of other members of the replica set based on
+the name and the hostname you provide.
 
 These operations add two shards, provided by: