docs-11115 rs.add and initial sync

Author: kay-kim

source/includes/apiargs-method-rs.add-param.yaml

@@ -1,19 +1,34 @@
 arg_name: param
 description: |
-  The new member to add to the replica set.
+  
+  The new member to add to the replica set. Specify either as a string
+  or a configuration document:
 
-  If a string, specify the hostname and optionally the port number for
-  the new member. See :ref:`rs-add-hostname` for an example.
+  - If a document, specify a replica set member configuration document
+    as found in the :rsconf:`members` array. You must specify the
+    :rsconf:`~members[n].host` field in the member configuration
+    document.
 
-  If a document, specify a replica set member configuration document as
-  found in the :rsconf:`members` array. You must
-  specify :rsconf:`members[n]._id` and the
-  :rsconf:`members[n].host` fields in the member
-  configuration document. See
-  :ref:`rs-add-member-configuration-document` for an example.
+    .. code-block:: javascript
+  
+       {
+         _id: <int>,
+         host: <string>,        // required
+         arbiterOnly: <boolean>,
+         buildIndexes: <boolean>,
+         hidden: <boolean>,
+         priority: <number>,
+         tags: <document>,
+         slaveDelay: <int>,
+         votes: <number>
+      }
+
+    For a description of the configuration field, refer to
+    :rsconf:`members`.
+
+  - If a string, specify the hostname and optionally the port number
+    for the new member.
 
-  See :doc:`/reference/replica-configuration` document for full
-  documentation of all replica set configuration options
 interface: method
 name: host
 operation: rs.add

source/includes/steps-convert-replica-set-add-new-shard.yaml

@@ -1,4 +1,3 @@
-stepnum: 1
 title: 
   text: Start each member of the replica set with the appropriate options.
   character: "`"
@@ -25,7 +24,6 @@ post: |
 title: 
   text: Connect a :binary:`~bin.mongo` shell to a replica set member.
   character: "`"
-stepnum: 2
 ref: open-shell
 pre: |
   Connect a :binary:`~bin.mongo` shell to *one* member of the replica set
@@ -36,7 +34,6 @@ action:
   code: |
     mongo mongodb3.example.net
 ---
-stepnum: 3
 title: "Initiate the replica set."
 level: 4
 ref: initiate-rs
@@ -54,27 +51,16 @@ action:
   code: |
     rs.initiate( {
        _id : "rs1",
-       members: [ { _id : 0, host : "mongodb3.example.net:27017" } ]
+       members: [
+           { _id: 0, host: "mongodb3.example.net:27017" },
+           { _id: 1, host: "mongodb4.example.net:27017" },
+           { _id: 2, host: "mongodb5.example.net:27017" }
+       ]
     })
 ---
-stepnum: 4
-title: 
-  text: Add the remaining members to the replica set.
-  character: "`"
-ref: add-remaining-members
-pre: |
-  Add the remaining members with the :method:`rs.add()` method.
-action:
-  copyable: true
-  language: javascript
-  code: |
-    rs.add("mongodb4.example.net")
-    rs.add("mongodb5.example.net")
----
 title:
   text: "Connect a ``mongo`` shell to the ``mongos``."
   character: "`"
-stepnum: 5
 ref: connect-mongos
 action:
      copyable: true
@@ -85,7 +71,6 @@ action:
 title:
   text: Add the shard.
   character: "`"
-stepnum: 6
 ref: add-mongos-shard
 pre: |
   In a :binary:`~bin.mongo` shell connected to the :binary:`~bin.mongos`, add
@@ -95,4 +80,4 @@ action:
   language: javascript
   code: |
     sh.addShard( "rs1/mongodb3.example.net:27017,mongodb4.example.net:27017,mongodb5.example.net:27017" )
-...
+...

source/includes/steps-replace-disabled-config-server.yaml

@@ -1,5 +1,4 @@
 title: Start the replacement config server.
-stepnum: 1
 ref: start-config-server
 pre: |
 
@@ -15,31 +14,65 @@ action:
       mongod --configsvr --replSet <replicaSetName> --bind_ip localhost,<ip address of the mongod host>
 ---
 title: Add the new config server to the replica set.
-stepnum: 2
 ref: add-to-replica-set
 pre: |
     Connect a :binary:`~bin.mongo` shell to the primary of the config server
     replica set and use :method:`rs.add()` to add the new member.
+    
+    .. tip:: 
+
+       .. include:: /includes/tip-repl-set-add-members.rst
+
 action:
    language: javascript
    code: |
-     rs.add("<hostnameNew>:<portNew>")
+      rs.add( { host: "<hostnameNew>:<portNew>", priority: 0, votes: 0 } )
+      
 post: |
    The initial sync process copies all the data from one member of the
    config server replica set to the new member without restarting.
 
    :binary:`~bin.mongos` instances automatically recognize the change in the
    config server replica set members without restarting.
 ---
+title: Update the newly added config server's votes and priority settings.
+ref: reconfig
+
+content: |
+
+   a. Ensure that the new member has reached :replstate:`SECONDARY`
+      state. To check the state of the replica set members, run
+      :method:`rs.status()`:
+
+      .. cssclass:: copyable-code
+      .. code-block:: javascript
+
+         rs.status()
+      
+   #. Reconfigure the replica set to update the votes and priority of
+      the new member:
+
+      .. code-block:: javascript
+
+         var cfg = rs.conf();
+
+         cfg.members[n].priority = 1;  // Substitute the correct array index for the new member
+         cfg.members[n].votes = 1;     // Substitute the correct array index for the new member
+
+         rs.reconfig(cfg)
+ 
+      where ``n`` is the array index of the new member in the
+      :rsconf:`members` array.
+
+   .. include:: /includes/warning-rs-reconfig.rst
+---
 title: Shut down the member to replace.
-stepnum: 3
 ref: shut-down-old-member
 content: |
    If replacing the primary member, step down the primary first before
    shutting down.
 ---
 title: Remove the member to replace from the config server replica set.
-stepnum: 4
 ref: remove-old-member
 pre: |
     Upon completion of initial sync of the replacement config server,
@@ -56,7 +89,6 @@ post: |
    .. end-for-migration-steps
 ---
 title: "If necessary, update ``mongos`` configuration or DNS entry."
-stepnum: 5
 ref: update-mongos-setting
 pre: |
     With replica set config servers, the :binary:`~bin.mongos` instances specify

source/includes/tip-repl-set-add-members.rst

@@ -0,0 +1,13 @@
+When a newly added secondary has its :rsconf:`~members[n].votes` and
+:rsconf:`~members[n].priority` settings greater than zero, during
+its initial sync, the secondary still counts as a voting member even
+though it cannot serve reads nor become primary because its data is
+not yet consistent.
+
+This can lead to a case where a majority of the voting members are
+online but no primary can be elected. To avoid such situations,
+consider adding the new secondary initially with
+:rsconf:`priority :0 <members[n].priority>` and :rsconf:`votes :0
+<members[n].votes>`. Then, once the member has transitioned into
+:replstate:`SECONDARY` state, use :method:`rs.reconfig()` to update its
+priority and votes.

source/reference/method/rs.add.txt

@@ -18,6 +18,7 @@ Definition
    Adds a member to a :term:`replica set`. To run the method, you must
    connect to the :term:`primary` of the replica set.
 
+
    .. include:: /includes/apiargs/method-rs.add-param.rst
 
    :method:`rs.add()` provides a wrapper around some of the
@@ -40,56 +41,134 @@ which will disconnect the shell (such as adding a new member with
 a higher priority than the current primary). In such cases, the :binary:`~bin.mongo`
 shell may display an error even if the operation succeeds.
 
+.. tip::
+
+   .. include:: /includes/tip-repl-set-add-members.rst
+
 Example
 -------
 
-.. _rs-add-hostname:
+.. _rs-add-member-new-replica-set:
 
-Pass a Hostname String to ``rs.add()``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Add a Secondary to a New Replica Set
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The following operation adds a :binary:`~bin.mongod` instance, running on
-the host ``mongodb3.example.net`` and accessible on the default port
-``27017``:
+To add a new secondary member with default vote and priority settings
+to a new replica set, you can call the :method:`rs.add()` method with:
 
-.. code-block:: javascript
+- Member Configuration Document
 
-   rs.add('mongodb3.example.net:27017')
+  .. cssclass:: copyable-code
 
-If ``mongodb3.example.net`` is an arbiter, use the following form:
+  .. code-block:: javascript
 
-.. code-block:: javascript
+     rs.add( { host: "mongodbd4.example.net:27017" } )
 
-   rs.add('mongodb3.example.net:27017', true)
+- Host name
 
-.. include:: /includes/extracts/arbiters-and-pvs-with-reference.rst
+  .. cssclass:: copyable-code
+
+  .. code-block:: javascript
+
+     rs.add( "mongodbd4.example.net:27017" )
 
 .. _rs-add-member-configuration-document:
 
-Pass a Member Configuration Document to ``rs.add()``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Add a Secondary to an Existing Replica Set
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. tip::
+
+   .. include:: /includes/tip-repl-set-add-members.rst
+
+To add a new secondary member with default vote and priority settings
+to an existing replica set:
+
+#. Add the member initially as a :ref:`non-voting
+   <replica-set-non-voting-members>`, :doc:`priority 0
+   </core/replica-set-priority-0-member>` member:
+
+   .. cssclass:: copyable-code
+
+   .. code-block:: javascript
+
+        rs.add( { host: "mongodbd4.example.net:27017", priority: 0, votes: 0 } )
+
+#. Ensure that the new member has reached :replstate:`SECONDARY` state.
+   To check the state of the replica set members, run
+   :method:`rs.status()`:
+
+   .. cssclass:: copyable-code
+   .. code-block:: javascript
+
+      rs.status()
+
+#. Reconfigure the replica set to update the votes and priority of the
+   new member:
+
+   .. code-block:: javascript
 
-.. versionchanged:: 3.0.0
-   Previous versions required an ``_id`` field in the document you
-   passed to :method:`rs.add()`. After 3.0.0 you can omit the
-   ``_id`` field in this document.
-   :rsconf:`members[n]._id` describes the requirements for specifying ``_id``.
+      var cfg = rs.conf();
+
+      cfg.members[n].priority = 1;  // Substitute the correct array index for the new member
+      cfg.members[n].votes = 1;     // Substitute the correct array index for the new member
+
+      rs.reconfig(cfg)
+
+   where ``n`` is the array index of the new member in the
+   :rsconf:`members` array.
+
+.. include:: /includes/warning-rs-reconfig.rst
+
+.. _rs-add-priority-0:
+
+Add a Priority 0 Member to a Replica Set
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The following operation adds a :binary:`~bin.mongod` instance, running on
 the host ``mongodb4.example.net`` and accessible on the default port
 ``27017``, as a :doc:`priority 0 </core/replica-set-priority-0-member>`
 secondary member:
 
+.. cssclass:: copyable-code
+
 .. code-block:: javascript
 
    rs.add( { host: "mongodbd4.example.net:27017", priority: 0 } )
 
-You must specify the
-:rsconf:`members[n].host` field in the member
+You must specify the :rsconf:`members[n].host` field in the member
 configuration document.
 
-See the :doc:`/reference/replica-configuration` for the available
-replica set member configuration settings.
+See the :rsconf:`members` for the available replica set member
+configuration settings.
+
+.. _rs-add-hostname:
+
+Add an Arbiter to a Replica Set
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following operation adds a :binary:`~bin.mongod` instance, running on
+the host ``mongodb3.example.net`` and accessible on the default port
+``27017`` as an arbiter:
+
+- Member Configuration Document
+
+  .. cssclass:: copyable-code
+
+  .. code-block:: javascript
+  
+     rs.add( { host: "mongodb3.example.net:27017", arbiterOnly: true } )
+
+- Host name
+
+  .. cssclass:: copyable-code
+
+  .. code-block:: javascript
+
+     rs.add("mongodb3.example.net:27017"'", true)
+
+.. include:: /includes/extracts/arbiters-and-pvs-with-reference.rst
+
 
 See also: