DOCS-11064: 3.6 shard repl sets

Author: kay-kim

source/core/master-slave.txt

@@ -256,9 +256,7 @@ Convert a Master-Slave Deployment to a Replica Set
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 To convert a master-slave deployment to a replica set, restart the
-current master as a one-member replica set. Then remove the data
-directories from previous secondaries and add them as new secondaries to
-the new replica set.
+current master as a one-member replica set.
 
 1. To confirm that the current instance is master, run:
 
@@ -324,10 +322,9 @@ the new replica set.
 
       rs.status()
 
-You can now follow the :doc:`convert a standalone to a replica set
-</tutorial/convert-standalone-to-replica-set>` tutorial to deploy your
-replica set, picking up from the :ref:`Expand the Replica Set
-<expand-the-replica-set>` section.
+To add the former slaves as secondaries to the replica set, remove the
+their data directories and add to the replica set. See
+:doc:`/tutorial/expand-replica-set` to add new members to a replica set.
 
 Failing over to a Slave (Promotion)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

source/includes/apiargs-dbcommand-addShard-field.yaml

@@ -1,16 +1,16 @@
-arg_name: field
+name: addShard
 description: |
-  The replica set name and hostname of at least one member of the
-  shard's replica set. Include the port number if the instance is
-  running on a non-standard port. All additional hostnames must be comma
-  separated and belong to the same replica set. For example:
+
+  The replica set name, hostname, and port of at least one member of
+  the shard's replica set. Any additional replica set member hostnames
+  must be comma separated. For example:
 
   .. code-block:: sh
 
      <replica_set>/<hostname><:port>,<hostname><:port>, ...
 
 interface: dbcommand
-name: addShard
+arg_name: field
 operation: addShard
 optional: false
 position: 1

source/includes/apiargs-method-sh.addShard-param.yaml

@@ -1,9 +1,8 @@
 arg_name: param
 description: |
-  The replica set name and hostname of at least one member of the
-  shard's replica set. Include the port number if the instance is
-  running on a non-standard port. All additional hostnames must be comma
-  separated and belong to the same replica set. For example:
+  The replica set name, hostname, and port of at least one member of
+  the shard's replica set. Any additional replica set member hostnames
+  must be comma separated. For example:
 
   .. code-block:: sh
 

source/includes/fact-bind-ip-sharded-clusters.rst

@@ -2,8 +2,5 @@
 
    The :option:`--bind_ip <mongod --bind_ip>` option must be specified when
    the sharded cluster members are run on different hosts or if
-   remote clients connect to the sharded cluster. If you are
-   deploying the entire sharded cluster on a single host and
-   do not require external client connections, you can omit the
-   :option:`--bind_ip <mongod --bind_ip>` option. For more information, see
+   remote clients connect to the sharded cluster. For more information, see
    :ref:`3.6-bind_ip-compatibility`.

source/includes/options-conf.yaml

@@ -1384,7 +1384,7 @@ post: |
      Setting ``sharding.clusterRole`` requires the :binary:`~bin.mongod`
      instance to be running with replication. To deploy the instance as
      a replica set member, use the :setting:`~replication.replSetName`
-     setting and specify the name of the replica set to join.
+     setting and specify the name of the replica set.
 
   The {{role}} setting is available only for :binary:`~bin.mongod`.
 ---

source/includes/options-mongod.yaml

@@ -1149,15 +1149,9 @@ description: |
 
      .. versionchanged:: 3.6
 
-     You must deploy shards as replica sets with the :option:`--replSet`
-     option or :setting:`~replication.replSetName` setting
-     specified. To deploy sharded clusters with shard replica
-     sets, follow the appropriate tutorial depending on your
-     :ref:`sharding strategy<sharding-strategy>`:
+     You must deploy shards as replica sets. See the :option:`--replSet`
+     option to deploy {{program}} as part of a replica set.
 
-     - :doc:`/tutorial/deploy-sharded-cluster-hashed-sharding`
-
-     - :doc:`/tutorial/deploy-sharded-cluster-ranged-sharding`
 
 optional: false
 ---

source/includes/steps-3.6-upgrade-sharded-cluster.yaml

@@ -45,17 +45,16 @@ content: |-
          the |oldversion| binary with the |newversion| binary.
 
       #. Start the |newversion| binary with the :option:`--configsvr <mongod --configsvr>`,
-         :option:`--replSet <mongod --replSet>`, :option:`--port <mongod --port>`, and :option:`--bind_ip <mongod --bind_ip>`
-         options. Include any optional command line options used by the
-         previous deployment:
+         :option:`--replSet <mongod --replSet>`, and :option:`--port <mongod --port>`. 
+         Include any other options as used by the deployment.
+
+         .. include:: /includes/fact-bind-ip-sharded-clusters.rst
 
          .. cssclass:: copyable-code
          .. code-block:: sh
 
             mongod --configsvr --replSet <replSetName> --port <port> --dbpath <path> --bind_ip localhost,<ip address>
 
-         .. include:: /includes/fact-bind-ip-sharded-clusters.rst
-
          If using a :doc:`configuration file
          </reference/configuration-options>`, update the file to
          specify :setting:`sharding.clusterRole: configsvr
@@ -76,7 +75,7 @@ content: |-
             storage:
                dbpath: <path>
 
-         Include any other configuration as appropriate for your deployment.
+         Include any other settings as appropriate for your deployment.
 
       #. Wait for the member to recover to ``SECONDARY`` state before
          upgrading the next secondary member. To check the member's state,
@@ -138,11 +137,9 @@ title: Upgrade the shards.
 level: 4
 ref: 3.6-upgrade-shards
 content: |-
-   Upgrade the shards one at a time. If you are running standalone
-   shards, first convert them to a
-   :doc:`replica set</tutorial/convert-standalone-to-replica-set>`.
-   
-   For each shard:
+   Upgrade the shards one at a time.
+
+   For each shard replica set:
 
    1. Upgrade the :ref:`secondary <replica-set-secondary-members>`
       members of the replica set one at a time:
@@ -250,11 +247,7 @@ content: |-
    and restart. Include any other configuration as appropriate for your
    deployment.
 
-   If the sharded cluster members are run on different hosts or
-   if you wish remote clients to connect to the sharded cluster,
-   you must also specify ``--bind_ip`` (or the
-   :setting:`net.bindIp` setting). For more information, see
-   :ref:`3.6-bind_ip-compatibility`.
+   .. include:: /includes/fact-bind-ip-sharded-clusters.rst
 
    .. cssclass:: copyable-code
    .. code-block:: sh

source/reference/command/addShard.txt

@@ -15,11 +15,11 @@ Definition
 
 .. dbcommand:: addShard
 
-   Adds a :term:`replica set` to a :term:`sharded cluster`.
+   Adds a shard replica set to a :term:`sharded cluster`.
 
    Run :dbcommand:`addShard` when connected to a :binary:`~bin.mongos`
-   instance.  The command takes the following form when adding a replica
-   set as a shard:
+   instance. The command takes the following form to add a shard
+   replica set:
 
    .. code-block:: javascript
 
@@ -68,5 +68,5 @@ The following command adds a replica set as a shard:
 .. warning::
 
    Do not use ``localhost`` for the hostname unless your
-   :term:`configuration server <config database>` is also running on
+   config server is also running on
    ``localhost``.

source/reference/method/sh.addShard.txt

@@ -13,9 +13,9 @@ sh.addShard()
 Definition
 ----------
 
-.. method:: sh.addShard(host)
+.. method:: sh.addShard(<url>)
 
-   Adds a :term:`replica set` to a :term:`sharded cluster`. This method
+   Adds a shard replica set to a :term:`sharded cluster`. This method
    must be run on a :binary:`~bin.mongos` instance.
 
    The :method:`sh.addShard()` method has the following parameter:
@@ -31,7 +31,7 @@ Definition
    .. warning::
 
       Do not use ``localhost`` for the hostname unless your
-      :term:`configuration server <config database>`
+      config server
       is also running on ``localhost``.
 
       .. |mongodb-package| replace:: :binary:`~bin.mongos`

source/release-notes/3.6-compatibility.txt

@@ -22,6 +22,17 @@ Localhost Binding Compatibility Changes
 
 .. include:: /includes/fact-bind-to-all-ips.rst
 
+Shard Replica Set
+-----------------
+
+Starting in 3.6, shards must be replica sets. To upgrade your sharded
+cluster to version 3.6, the shard servers must be running as a replica
+set.
+
+To convert an existing shard standalone instance to a shard replica
+set, see :doc:`/tutorial/convert-standalone-to-replica-set`.
+
+
 HTTP Interface and REST API
 ---------------------------
 

source/release-notes/3.6-upgrade-sharded-cluster.txt

@@ -40,13 +40,16 @@ clients to connect to your sharded cluster.
 
 For more information, see :ref:`3.6-bind_ip-compatibility`
 
-Shard Servers Require Replication
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Shard Replica Sets
+~~~~~~~~~~~~~~~~~~
 
 Starting in MongoDB 3.6, :binary:`~bin.mongod` instances with the shard
-server role must be replica set members. The following procedure uses
-the :option:`--replSet <mongod --replSet>` option to deploy the instance as a member of the
-specified replica set.
+server role must be replica set members.
+
+To upgrade your sharded cluster to version 3.6, the shard servers must
+be running as a replica set. To convert an existing shard standalone
+instance to a shard replica set, see
+:doc:`/tutorial/convert-standalone-to-replica-set`.
 
 Prerequisites
 -------------

source/release-notes/3.6.txt

@@ -561,6 +561,13 @@ Replica Sets
 Sharded Clusters
 ----------------
 
+- Starting in 3.6, shards must be replica sets. To upgrade your sharded
+  cluster to version 3.6, the shard servers must be running as a
+  replica set. 
+
+  To convert an existing shard standalone instance to a shard replica
+  set, see :doc:`/tutorial/convert-standalone-to-replica-set`.
+
 - Added :parameter:`ShardingTaskExecutorPoolMaxConnecting` parameter
   for :binary:`~bin.mongos` to control the rate at which :binary:`~bin.mongos`
   adds connections to a :binary:`~bin.mongod` instance.
@@ -571,8 +578,7 @@ Sharded Clusters
 - The ``config.system.sessions`` collection in the ``config`` database
   may now be sharded.
 
-- To upgrade your sharded cluster to version 3.6, the shard servers must
-  be running as a replica set.
+
 
 General Enhancements
 --------------------

source/tutorial/convert-standalone-to-replica-set.txt

@@ -10,15 +10,15 @@ Convert a Standalone to a Replica Set
    :depth: 1
    :class: singlecol
 
-This tutorial describes the process for converting a
-:term:`standalone` :binary:`~bin.mongod` instance into a three-member
-:term:`replica set`.  Use standalone instances for testing and
-development, but always use replica sets in production. To install a
-standalone instance, see the :ref:`installation tutorials
-<tutorials-installation>`.
+This tutorial describes the process for converting a :term:`standalone`
+:binary:`~bin.mongod` instance into a :term:`replica set`. Use
+standalone instances for testing and development, but always use
+replica sets in production. To install a standalone instance, see the
+:ref:`installation tutorials <tutorials-installation>`.
 
-To deploy a replica set without using a pre-existing :binary:`~bin.mongod`
-instance, see :doc:`/tutorial/deploy-replica-set`.
+To deploy a replica set without using a pre-existing
+:binary:`~bin.mongod` instance, see :doc:`/tutorial/deploy-replica-set`
+instead.
 
 Procedure
 ---------
@@ -40,6 +40,10 @@ Procedure
 
    .. include:: /includes/fact-unique-replica-set-names.rst
 
+   If converting a shard standalone instance to a shard replica set,
+   the shard replica set name must not use the same name as the config
+   server replica set.
+
    For more information on configuration options, see
    :doc:`/reference/configuration-options` and the :binary:`~bin.mongod`
    manual page.
@@ -52,36 +56,57 @@ Procedure
 
       rs.initiate()
 
-   The replica set is now operational.
+   The replica set is now operational. To view the replica set
+   configuration, use :method:`rs.conf()`. To check the status of the
+   replica set, use :method:`rs.status()`.
 
-   To view the replica set configuration, use :method:`rs.conf()`. To
-   check the status of the replica set, use :method:`rs.status()`.
+   .. important::
 
-.. _expand-the-replica-set:
+      If converting a shard standalone instance to a shard replica set, you
+      must also :ref:`update the shard information <update-shard-host-info>`.
 
 To add members to this replica set, use the :method:`rs.add()` method.
 For more information on adding members to a replica set, see
 :doc:`/tutorial/expand-replica-set`.
 
+.. _update-shard-host-info:
+
 Sharding Considerations
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-If the new replica set is part of a :term:`sharded cluster`, change
-the shard host information in the :term:`config database` by doing
-the following:
+If the new replica set is a shard replica set, change the shard
+information in the :term:`config database` by doing the following:
 
 #. Connect to one of the sharded cluster's :binary:`~bin.mongos`
-   instances and issue a command in the following form:
+   instances and retrieve the shard information:
+
+   .. code-block:: javascript
+
+      var myShard = db.getSiblingDB("config").shards.findOne( { _id: "<name>"} )
+
+   Replace ``<name>`` with the name of the shard.
+
+   .. note:: 
+
+      The ``<name>`` of the shard is separate from the shard replica
+      set name. To retrieve the name of the shard, see the
+      :data:`shards <sh.status.shards._id>` section in the results from
+      the :method:`sh.status()` method.
+
+#. Update the ``host`` information with the replica set information:
+
+   .. code-block:: javascript
+
+      myShard.host = "<replica-set>/<member,><member,><...>"
+
+   Replace ``<replica-set>`` with the name of the replica set. Replace
+   ``<member,><member,><...>`` with the list of the replica set members.
+
+#. Save the information.
 
    .. code-block:: javascript
 
-      db.getSiblingDB("config").shards.save( {_id: "<name>", host: "<replica-set>/<member,><member,><...>" } )
+      db.getSiblingDB("config").shards.save( myShard )
 
-   Replace ``<name>`` with the name of the shard. Replace
-   ``<replica-set>`` with the name of the replica set. Replace
-   ``<member,><member,><>`` with the list of the members of the
-   replica set.
+#. Restart all :binary:`~bin.mongos` instances and all shard binaries.
 
-#. Restart all :binary:`~bin.mongos` instances. If possible, restart all
-   components of the replica sets (i.e., all :binary:`~bin.mongos` and
-   all shard :binary:`~bin.mongod` instances).