From 415a101f881e1536cc61d5c3ddbe46a8bbbaa87f Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Tue, 11 Sep 2012 17:52:54 -0400 Subject: [PATCH] DOCS-324 consolidated procedure for add members --- source/administration/replica-sets.txt | 40 +------ source/tutorial/expand-replica-set.txt | 139 +++++++++++++++++-------- 2 files changed, 102 insertions(+), 77 deletions(-) diff --git a/source/administration/replica-sets.txt b/source/administration/replica-sets.txt index 065caa5c066..903633ec583 100644 --- a/source/administration/replica-sets.txt +++ b/source/administration/replica-sets.txt @@ -341,9 +341,9 @@ Before adding a new member to an existing :term:`replica set`, do one of the following to prepare the new member's :term:`data directory `: - Make sure the new member's data directory *does not* contain data. The - new member will copy the data directory from an existing member. + new member will copy the data from an existing member. - If the new member is in a :term:`recovering` state, it must exit + If the new member is in a :term:`recovering` state, it must exit and become a :term:`secondary` before MongoDB can copy all data as part of the replication process. This process takes time but does not require administrator intervention. @@ -364,39 +364,8 @@ the following to prepare the new member's :term:`data directory `: Use :method:`db.printReplicationInfo()` to check the current state of replica set members with regards to the oplog. -To add a member to an existing replica set, deploy a new -:program:`mongod` instance, specifying the name of the replica set -(i.e. :data:`setname `) on the command line with the -:option:`--replSet ` option or in the configuration -file with the :setting:`replSet`. Take note of the host name and port -information for the new :program:`mongod` instance. - -Then log in to the current :term:`primary` using the :program:`mongo` -shell. Issue the :method:`db.isMaster()` command when connected to *any* -member of the set to determine the current primary. Issue the -following command to add the new member to the set: - -.. code-block:: javascript - - rs.add("mongo2.example.net:27017") - -Alternately, specify an entire configuration document with some or all -of the fields in a :data:`members ` document. For -example: - -.. code-block:: javascript - - rs.add({_id: 1, host: "mongo2.example.net:27017", priority: 0, hidden: true}) - -This configures a :term:`hidden member` that is accessible at -``mongo2.example.net:27017``. See :data:`host `, -:data:`priority `, and :data:`hidden -` for more information about these settings. When -you specify a full configuration object with :method:`rs.add()`, you must -declare the ``_id`` field, which is not automatically populated in -this case. - -.. seealso:: :doc:`/tutorial/expand-replica-set`. +For the procedure to add a member to a replica set, see +:doc:`/tutorial/expand-replica-set`. .. _replica-set-admin-procedure-remove-members: @@ -446,7 +415,6 @@ Use :method:`rs.reconfig()` to change the value of the number. :method:`rs.reconfig()` will not change the value of :data:`members[n]._id`. - .. code-block:: javascript cfg = rs.conf() diff --git a/source/tutorial/expand-replica-set.txt b/source/tutorial/expand-replica-set.txt index ffd85f7cce9..59bc6821381 100644 --- a/source/tutorial/expand-replica-set.txt +++ b/source/tutorial/expand-replica-set.txt @@ -7,12 +7,14 @@ Add Members to a Replica Set Overview -------- -This is a tutorial explaining how to add an additional node to an +This tutorial explains how to add an additional member to an existing replica set. -Before adding new members, note the -:doc:`/administration/replication-architectures` documentation for -more background on replication deployment patterns. +Before adding a new member, see the :ref:`replica-set-admin-procedure-add-member` +topic in the :doc:`/administration/replica-sets` document. + +For background on replication deployment patterns, see the +:doc:`/administration/replication-architectures` document. Requirements ------------ @@ -20,25 +22,28 @@ Requirements #. An active replica set. #. A new MongoDB system capable of supporting your dataset, accessible by - the active replica set through the network. + the active replica set through the network. If neither of these conditions are satisfied, please use the MongoDB :ref:`installation tutorial ` and the -":doc:`/tutorial/deploy-replica-set`" guide instead. +:doc:`/tutorial/deploy-replica-set` guide instead. + +Procedures +---------- -Procedure ---------- +.. _procedure-assumption-add-member-rs: -For the following procedure, examples are provided using the following +The examples in this procedure use the following configuration: -- The active replica set: ``rs0`` +- The active replica set is ``rs0``. -- The new MongoDB replica set to be added: ``mongodb3.example.net``. +- The new member to be added is ``mongodb3.example.net``. -- :program:`mongod` instance running on default port: ``27017``. +- The :program:`mongod` instance default port is ``27017``. -- The ``mongodb.conf`` on the new replica set system resembling the following: +- The ``mongodb.conf`` configuration file exists in the ``/etc`` + directory and contains the following replica set information: .. code-block:: cfg @@ -54,53 +59,105 @@ configuration: replSet = rs0 -For more documentation of the configuration options used above refer to: -:setting:`dbpath`, :setting:`port`, :setting:`replSet`, -:setting:`bind_ip`, and :setting:`fork`. Consider any additional -:doc:`configuration options ` that -your deployment may require. +For more information on configuration options, see +:doc:`/reference/configuration-options`. -#. On the primary node, Start the :program:`mongod` process with the - following command: +.. _replica-set-add-member: - .. code-block:: sh +Add a Member to an Existing Replica Set +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - mongod --config /etc/mongodb.conf +This procedure uses the above :ref:`example configuration `. - .. note:: +1. Deploy a new :program:`mongod` instance, specifying the name of the + replica set. You can do this one of two ways: - The primary node is the only node which can add or remove - members to the replica set. If you do not know the primary - node, log into any of the existing members of the current - replica set by issuing the following command: + - Using the ``mongodb.conf`` file. On the :term:`primary`, issue a + command that resembles the following: - .. code-block:: sh + .. code-block:: sh - mongo mongodb0.example.net - - If this instance is not currently the :term:`primary` node, use - the :method:`db.isMaster()` function to determine which node is in - the :data:`isMaster.primary` field. Issue the following command. + mongod --config /etc/mongodb.conf + + - Using command line arguments. On the :term:`primary`, issue command + that resembles the following: + + .. code-block:: sh + + mongod --replSet rs0 + + Take note of the host name and port information for the new + :program:`mongod` instance. + +#. Open a :program:`mongo` shell connected to the replica set's primary: + + .. code-block:: sh + + mongo + + .. note:: + + The primary is the only member that can add or remove members from + the replica set. If you do not know which member is the primary, + log into any member of the replica set using :program:`mongo` and + issue the :method:`db.isMaster()` command to determine which + member is in the :data:`isMaster.primary` field. For example: .. code-block:: javascript + mongo mongodb0.example.net + db.isMaster() - Now disconnect from the current client and reconnect to the - primary node. + If you are not connected to the primary, disconnect from the + current client and reconnect to the primary. -#. Now issue the following command to add the new member to the +#. In the :program:`mongo` shell, issue the following command to add the new member to the replica set. .. code-block:: javascript rs.add("mongodb3.example.net") -Congratulations! You have successfully expanded an existing replica -set. You can use the :method:`rs.status()` function to provide an -overview of :doc:`replica set status `, or -the :method:`rs.conf()` for the complete :doc:`replica set -configuration `. + .. note:: + + You can also include the port number, depending on your setup: + + .. code-block:: javascript + + rs.add("mongodb3.example.net:27017") + +#. Verify that the member is now part of the replica set by + calling the :method:`rs.config()` method, + which displays the :doc:`replica set configuration `: + + .. code-block:: javascript + + rs.config() + + You can use the :method:`rs.status()` function to provide an + overview of :doc:`replica set status `. + +.. _replica-set-add-member-alternate-procedure: + +Add a Member to an Existing Replica Set (Alternate Procedure) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Alternately, you can add a member to a replica set by specifying an +entire configuration document with some or all of the fields in a +:data:`members ` document. For example: + +.. code-block:: javascript + + rs.add({_id: 1, host: "mongodb3.example.net:27017", priority: 0, hidden: true}) + +This configures a :term:`hidden member` that is accessible at +``mongodb3.example.net:27017``. See :data:`host `, +:data:`priority `, and :data:`hidden +` for more information about these settings. When you +specify a full configuration object with :method:`rs.add()`, you must +declare the ``_id`` field, which is not automatically populated in this +case. Production Notes ----------------