From 52af779c05decf520a7ba939f69f5dbdd1b4afeb Mon Sep 17 00:00:00 2001 From: Zack Brown Date: Wed, 10 Jul 2013 15:26:37 -0400 Subject: [PATCH] DOCS-927 migrate state list to its own file and expand. --- source/includes/replica-states.rst | 53 ++++---- source/reference/command/replSetGetStatus.txt | 18 +-- source/reference/replica-states.txt | 114 ++++++++++++++++++ 3 files changed, 150 insertions(+), 35 deletions(-) create mode 100644 source/reference/replica-states.txt diff --git a/source/includes/replica-states.rst b/source/includes/replica-states.rst index f4095969aa2..bac0c6dfe5c 100644 --- a/source/includes/replica-states.rst +++ b/source/includes/replica-states.rst @@ -4,48 +4,55 @@ * - **Number** - **Name** - - **State** + - **State Description** * - 0 - - ``STARTUP`` - - Start up, phase 1 (parsing configuration.) Not eligible to vote. + - :replstate:`STARTUP` + + - Cannot vote. All members start up in this state. The + :program:`mongod` parses the :doc:`replica set configuration document ` while in :replstate:`STARTUP`. * - 1 - - ``PRIMARY`` - - Primary. Eligible to vote. + - :replstate:`PRIMARY` + - Can vote. The :doc:`primary ` is the only member to accept write operations. * - 2 - - ``SECONDARY`` - - Secondary. Eligible to vote. + - :replstate:`SECONDARY` + - Can vote. The :doc:`secondary ` replicates the data store. * - 3 - - ``RECOVERING`` - - Member is recovering (initial sync, post-rollback, stale members.) Eligible to vote. + - :replstate:`RECOVERING` + - Can vote. Members either perform startup self-checks, or transition + from completing a :doc:`rollback ` or :doc:`resync `. * - 4 - - ``FATAL`` - - Member has encountered an unrecoverable error. Not eligible to vote. + - :replstate:`FATAL` + - Cannot vote. Has encountered an unrecoverable error. * - 5 - - ``STARTUP2`` - - Start up, phase 2 (forking threads.) Not eligible to vote. + - :replstate:`STARTUP2` + - Cannot vote. Forks replication and election threads before + becoming a secondary. * - 6 - - ``UNKNOWN`` - - Unknown (the set has never connected to the member.) Not eligible to vote. + - :replstate:`UNKNOWN` + - Cannot vote. Has never connected to the replica set. * - 7 - - ``ARBITER`` - - Member is an :term:`arbiter`. Eligible to vote. + - :replstate:`ARBITER` + - Can vote. :ref:`Arbiters ` do not replicate + data and exist solely to participate in elections. * - 8 - - ``DOWN`` - - Member is not accessible to the set. Not eligible to vote. + - :replstate:`DOWN` + - Cannot vote. Is not accessible to the set. * - 9 - - ``ROLLBACK`` - - Member is rolling back data. See :term:`rollback`. Eligible to vote. + - :replstate:`ROLLBACK` + - Can vote. Performs a :doc:`rollback `. * - 10 - - ``SHUNNED`` - - Member has been removed from replica set. Not eligible to vote. + - :replstate:`SHUNNED` + - Cannot vote. Was once in the replica set but has now been removed. + + diff --git a/source/reference/command/replSetGetStatus.txt b/source/reference/command/replSetGetStatus.txt index 34bb10d7d04..e9b55203aca 100644 --- a/source/reference/command/replSetGetStatus.txt +++ b/source/reference/command/replSetGetStatus.txt @@ -50,12 +50,9 @@ Output .. data:: replSetGetStatus.myState - The value of :data:`~replSetGetStatus.myState` reflects state of the current - replica set member. An integer between ``0`` and ``10`` represents - the state of the member. These integers map to states, as described - in the following table: - - .. include:: /includes/replica-states.rst + The value of + :data:`~replSetGetStatus.myState` is an integer between ``0`` and + ``10`` that represents the :doc:`replica state ` of the current member. .. data:: replSetGetStatus.members @@ -87,12 +84,9 @@ Output .. data:: replSetGetStatus.members.state - The value of the :data:`~replSetGetStatus.members.state` reflects - state of this replica set member. An integer between ``0`` and - ``10`` represents the state of the member. These integers map to - states, as described in the following table: - - .. include:: /includes/replica-states.rst + The value of + :data:`~replSetGetStatus.members.state` is an array of documents, each containing an integer between ``0`` and + ``10`` that represents the :doc:`replica state ` of the corresponding member. .. data:: replSetGetStatus.members.stateStr diff --git a/source/reference/replica-states.txt b/source/reference/replica-states.txt new file mode 100644 index 00000000000..57a855036e8 --- /dev/null +++ b/source/reference/replica-states.txt @@ -0,0 +1,114 @@ +========================= +Replica Set Member States +========================= + +.. default-domain:: mongodb + +Members of replica sets have states that reflect the startup process, basic +operations, and potential error states. + +.. include:: /includes/replica-states.rst + +States +------ + +Core States +~~~~~~~~~~~ +.. replstate:: PRIMARY + + Members in :replstate:`PRIMARY` state accept write operations. A replica set has only + one primary at a time. A :replstate:`SECONDARY` member becomes primary + after an :ref:`election `. Members in the :replstate:`PRIMARY` + state are eligible to vote. + +.. replstate:: SECONDARY + + Members in :replstate:`SECONDARY` state replicate the primary's data set + and can be configured to accept read operations. Secondaries are eligible to vote in + elections, and may be elected to the :replstate:`PRIMARY` state if the + primary becomes unavailable. + +.. replstate:: ARBITER + + Members in :replstate:`ARBITER` state do not replicate data or accept write operations. + They are eligible to vote, and exist solely to break a tie during + elections. Replica sets should only have a member in the :replstate:`ARBITER` state + if the set would otherwise have an even number of members, and could suffer + from tied elections. Like primaries, there should only be at most one arbiter + in any replica set. + +See :doc:`/core/replica-set-members` for more information on core states. + +Initialization States +~~~~~~~~~~~~~~~~~~~~~ + +.. replstate:: STARTUP + + Each member of a replica set starts up in :replstate:`STARTUP` + state. :program:`mongod` then loads that member's replica set configuration, + and transitions the member's state to :replstate:`STARTUP2`. Members in + :replstate:`STARTUP` are not eligible to vote. + +.. replstate:: STARTUP2 + + Each member of a replica set enters the :replstate:`STARTUP2` state as + soon as :program:`mongod` finishes loading that member's + configuration. While in the :replstate:`STARTUP2` state, the member + creates threads to handle internal replication operations. Members are in the + :replstate:`STARTUP2` state for a short period of time before entering the :replstate:`RECOVERING` state. + Members in the :replstate:`STARTUP2` state are not eligible to vote. + +.. replstate:: RECOVERING + + A member of a replica set enters this state if it is not yet ready to + accept reads. Members in the :replstate:`RECOVERING` state cannot vote. The + :replstate:`RECOVERING` state can occur during normal operation, and doesn't + necessarily reflect an error condition. + + During startup, members transition through :replstate:`RECOVERING` after + :replstate:`STARTUP2` and before becoming :replstate:`SECONDARY`. + + During normal operation, if a :term:`secondary` falls behind the + other members of the replica set, it may need to :doc:`resync + ` with the + rest of the set. While resyncing, the member enters the + :replstate:`RECOVERING` state. + + Likewise, whenever a :term:`primary` is replaced in an election, its data + collection may contain documents that did not have time to replicate to + the :term:`secondary` members. In this case those extra writes are rolled + back and discarded. During :doc:`rollback `, + the member will have :replstate:`RECOVERING` state. + +Error States +~~~~~~~~~~~~ + +Members in any error state can't vote. + +.. replstate:: FATAL + + Members that encounter an unrecoverable error enter the :replstate:`FATAL` + state. Members in this state requires administrator intervention. + +.. replstate:: UNKNOWN + + Members that have never communicated status information to the replica + set are in the :replstate:`UNKNOWN` state. + +.. replstate:: DOWN + + Members that lose their connection to the replica set enter the + :replstate:`DOWN` state. + +.. replstate:: SHUNNED + + Members that are removed from the replica set enter the :replstate:`SHUNNED` + state. + +.. replstate:: ROLLBACK + + When a :replstate:`SECONDARY` rolls back a write operation after + transitioning from :replstate:`PRIMARY`, it enters the :replstate:`ROLLBACK` + state. See :doc:`/core/replica-set-rollbacks`. + +