diff --git a/source/administration/replica-sets.txt b/source/administration/replica-sets.txt index b036ab07932..0bccf42c5bc 100644 --- a/source/administration/replica-sets.txt +++ b/source/administration/replica-sets.txt @@ -21,11 +21,15 @@ suggestions for administers of replica sets. The following tutorials provide task-oriented instructions for specific administrative tasks related to replica set operation. + .. Updates to this tutorial list should also be made in + source/replication.txt + - :doc:`/tutorial/deploy-replica-set` + - :doc:`/tutorial/convert-standalone-to-replica-set` - :doc:`/tutorial/expand-replica-set` - :doc:`/tutorial/deploy-geographically-distributed-replica-set` - :doc:`/tutorial/change-oplog-size` - - :doc:`/tutorial/convert-replica-set-to-replicated-shard-cluster` + - :doc:`/tutorial/force-member-to-be-primary` - :doc:`/tutorial/change-hostnames-in-a-replica-set` - :doc:`/tutorial/convert-secondary-into-arbiter` @@ -333,9 +337,9 @@ the event of a network partition. Procedures ---------- -For procedures on deploying replica sets, see the -:doc:`/administration/replication-architectures` document and the -:ref:`list of replica set tutorials `. +This section gives overview information on certain procedures. Most +procedures, however, are found in the :ref:`replica set tutorials +`. .. _replica-set-admin-procedure-add-member: diff --git a/source/replication.txt b/source/replication.txt index e4b33043c5e..38ffc134252 100644 --- a/source/replication.txt +++ b/source/replication.txt @@ -38,6 +38,9 @@ Tutorials The following tutorials describe certain replica set maintenance operations in detail: +.. Updates to this tutorial list should also be made in + source/administration/replica-sets.txt + .. toctree:: :maxdepth: 1 @@ -46,6 +49,7 @@ operations in detail: tutorial/expand-replica-set tutorial/deploy-geographically-distributed-replica-set tutorial/change-oplog-size + tutorial/force-member-to-be-primary tutorial/change-hostnames-in-a-replica-set tutorial/convert-secondary-into-arbiter diff --git a/source/tutorial/force-member-to-be-primary.txt b/source/tutorial/force-member-to-be-primary.txt new file mode 100644 index 00000000000..7e20411d850 --- /dev/null +++ b/source/tutorial/force-member-to-be-primary.txt @@ -0,0 +1,147 @@ +================================ +Force a Member to Become Primary +================================ + +.. default-domain:: mongodb + +Synopsis +-------- + +You can force a :term:`replica set` member to become :term:`primary` by +giving it a higher :data:`members[n].priority` value than any other +member in the set. + +Optionally, you also can force a member never to become primary by +setting its :data:`members[n].priority` value to ``0``, which means the +member can never seek :ref:`election ` as +primary. For more information, see +:ref:`replica-set-secondary-only-members`. + +Procedures +---------- + +.. _replica-set-force-member-to-be-primary-via-priority-setting: + +Force a Member to be Primary by Setting its Priority High +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionchanged:: 2.0 + +For more information on priorities, see :ref:`replica-set-node-priority`. + +This procedure assumes your current :term:`primary` is +``m1.example.net`` and that you'd like to instead make ``m3.example.net`` primary. +The procedure also assumes you have a three-member :term:`replica set` with the +configuration below. For more information on configurations, see :ref:`Replica Set +Configuration Use `. + +This procedure assumes this configuration: + +.. code-block:: javascript + + { + "_id" : "rs", + "version" : 7, + "members" : [ + { + "_id" : 0, + "host" : "m1.example.net:27017" + }, + { + "_id" : 1, + "host" : "m2.example.net:27017" + }, + { + "_id" : 2, + "host" : "m3.example.net:27017" + } + ] + } + +1. In the :program:`mongo` shell, use the following sequence of operations + to make ``m3.example.net`` the primary: + + .. code-block:: javascript + + cfg = rs.conf() + cfg.members[0].priority = 0.5 + cfg.members[1].priority = 0.5 + cfg.members[2].priority = 1 + rs.reconfig(cfg) + + This sets ``m3.example.net`` to have a higher + :data:`members[n].priority` value than the other :program:`mongod` + instances. + + The following sequence of events occur: + + - ``m3.example.net`` and ``m2.example.net`` sync with + ``m1.example.net`` (typically within 10 seconds). + + - ``m1.example.net`` sees that it no longer has highest priority and, + in most cases, steps down. ``m1.example.net`` *does not* step down + if ``m3.example.net``'s sync is far behind. In that case, + ``m1.example.net`` waits until ``m3.example.net`` is within 10 + seconds of its optime and then steps down. This minimizes the + amount of time with no primary on failover. + + - The step down forces on election in which ``m3.example.net`` + becomes primary based on its :data:`members[n].priority` value. + +#. Optionally, if ``m3.example.net`` is more than 10 seconds behind + ``m1.example.net``'s optime, and if you don't need to have a primary + designated within 10 seconds, you can force ``m1.example.net`` to + step down by running: + + .. code-block:: javascript + + db.adminCommand({replSetStepDown:1000000, force:1}) + + This prevents ``m1.example.net`` from being primary for 1,000,000 + seconds, even if there is no other member that can become primary. + When ``m3.example.net`` catches up with ``m1.example.net`` it syncs + and becomes primary. + + If you change your mind and would like to make ``m1.example.net`` + primary again while it waits for ``m3.example.net`` to catch up, + issue the following command to make ``m1.example.net`` seek election + again: + + .. code-block:: javascript + + db.adminCommand({replSetFreeze:0}) + +.. _replica-set-force-member-to-be-primary-via-dbcommands: + +Force a Member to be Primary Using Database Commands +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionchanged:: 1.8 + +For this procedure, assume you have a :term:`replica set` with members +``A``, ``B``, and ``C``. ``A`` is current :term:`primary`, and you want +``B`` to become primary. To do so you use :method:`rs.freeze()` and +:method:`rs.stepDown()`, which are wrappers for the +:dbcommand:`replSetFreeze` and :dbcommand:`replSetStepDown` commands. + +1. In a :program:`mongo` shell, run :method:`rs.status()` to ensure your replica + set is running as expected. + +#. In a :program:`mongo` shell connected to ``C``, freeze ``C`` so that it does + not attempt to become primary for 120 seconds. + + .. code-block:: javascript + + rs.freeze(120) + +#. In a :program:`mongo` shell connected to ``A``, step down ``A`` so that it is not + eligible to become primary for 120 seconds: + + .. code-block:: javascript + + rs.stepDown(120) + + ``B`` becomes primary. + + .. note:: During the transition, there is a short window when no member + is primary.