From 8142ee487a575f0130d8d0d40e463ba7e038396e Mon Sep 17 00:00:00 2001 From: Andrew Leung Date: Mon, 30 Jul 2012 10:20:27 -0400 Subject: [PATCH 1/5] initial fix of elections section --- source/core/replication-internals.txt | 53 ++++++++++++++------------- 1 file changed, 28 insertions(+), 25 deletions(-) diff --git a/source/core/replication-internals.txt b/source/core/replication-internals.txt index 06b5dfbfb75..e81ea4ccf2e 100644 --- a/source/core/replication-internals.txt +++ b/source/core/replication-internals.txt @@ -115,47 +115,50 @@ modify the configuration of an existing replica set. Elections --------- -When you initialize a replica set for the first time, and when -any failover occurs, an election takes place to decide which -member should become primary. - -Elections are the process that the members of a replica set use to -select the primary node in a cluster. Elections follow two events: -a primary node that "steps down" or a :term:`secondary` member that -loses contact with a :term:`primary` node. All members have one vote +When you initialize a replica set for the first time, and when any +failover occurs, an election takes place to decide which member should +become :term:`primary`. A primary is the only member in the replica +set that can accept write commands such as :func:`insert`, +:func:`update`, and :func:`delete`. +.. TODO verify above function references. + +Elections are the process replica set members use to +select the primary member in a cluster. Elections follow two events: +a primary member that "steps down" or a :term:`secondary` member that +loses contact with a :term:`primary` member. All members have one vote in an election, and every :program:`mongod` can veto an election. A single member's veto will invalidate the election. An existing primary will step down in response to the :dbcommand:`replSetStepDown` command, or if it sees that one of the current secondaries is eligible for election *and* has a higher -priority. A secondary node will call for an election if it cannot -establish a connection to a primary node. Primary nodes will also step +priority. A secondary will call for an election if it cannot +establish a connection to a primary member. A primary will also step down when they cannot contact a majority of the members of the replica -set. When the current primary steps down, it closes all open client +set. When the current primary member steps down, it closes all open client connections to prevent clients from unknowingly writing data to a -non-primary node. +non-primary member. In an election, every member, including :ref:`hidden ` members, :ref:`arbiters -`, and even recovering nodes get a single -vote. Members will give votes to every eligible node that calls an -election. +`, and even recovering members get a single +vote. Members will give votes to every eligible member that calls an +election. A primary is elected when one member receives a majority of the votes in the set. A member of the set will veto an election under the following conditions: -- If the node seeking an election is not a member of the voter's set. +- If the member seeking an election is not a member of the voter's set. -- If the node seeking an election is not up to date with the most +- If the member seeking an election is not up to date with the most recent operation accessible in the replica set. -- If the node seeking an election has a lower priority than another node +- If the member seeking an election has a lower priority than another member in the set that is also eligible for election. -- If the current :term:`primary` node has more recent operations - (i.e. a higher "optime") than the node seeking election, from the - perspective of the voting node. +- If the current :term:`primary` member has more recent operations + (i.e. a higher "optime") than the member seeking election, from the + perspective of the voting member. - The current primary will also veto an election if it has the same or more recent operations (i.e. a "higher or equal optime") than the @@ -163,16 +166,16 @@ conditions: .. note:: - All members of a replica set *can* veto an election, even if they + Any member of a replica set *can* veto an election, even if they are :ref:`non-voting members `. -The first node to receive votes from a majority of members in a set +The first member to receive votes from a majority of members in a set becomes the next primary until the next election. Be aware of the following conditions and possible situations: - Replica set members send heartbeats (pings) to each other every 2 seconds. If a heartbeat does not return for more than 10 seconds, - the other nodes mark the delinquent node as inaccessible. + the other members mark the delinquent member as inaccessible. - Replica set members only compare priorities with other members of the set. The absolute value of priorities does not have any impact on @@ -188,7 +191,7 @@ aware of the following conditions and possible situations: - If the member of the set with the highest priority is within 10 seconds of the latest oplog entry, then the set will *not* elect a - :term:`primary` until the node with the highest priority catches up + :term:`primary` until the member with the highest priority catches up to the latest operation. Syncing From bd7a76b4342a0389b7857ce13fe915eeacdf1a82 Mon Sep 17 00:00:00 2001 From: Andrew Leung Date: Mon, 30 Jul 2012 12:31:26 -0400 Subject: [PATCH 2/5] some updates from wiki --- source/core/replication-internals.txt | 32 +++++++++++++++++++++------ 1 file changed, 25 insertions(+), 7 deletions(-) diff --git a/source/core/replication-internals.txt b/source/core/replication-internals.txt index e81ea4ccf2e..351664e4ec1 100644 --- a/source/core/replication-internals.txt +++ b/source/core/replication-internals.txt @@ -118,16 +118,16 @@ Elections When you initialize a replica set for the first time, and when any failover occurs, an election takes place to decide which member should become :term:`primary`. A primary is the only member in the replica -set that can accept write commands such as :func:`insert`, -:func:`update`, and :func:`delete`. -.. TODO verify above function references. +set that can accept write commands such as :func:`insert() +`, :func:`update() `, +and :func:`remove() ` members, :ref:`arbiters `, and even recovering members get a single vote. Members will give votes to every eligible member that calls an -election. A primary is elected when one member receives a majority of the votes in the set. +election. A member of the set will veto an election under the following conditions: @@ -194,6 +194,24 @@ aware of the following conditions and possible situations: :term:`primary` until the member with the highest priority catches up to the latest operation. +Each member in a replica set has only one vote, by default. You may +change the number of votes each member has to allow for larger replica +sets. Each replica set is limited to 12 total members with 7 voting +members. + +- The number of votes is modifiable in the :data:`replica set configuration ` + +- The number of votes each member has can be any non-negative integer, + but it is highly recommended each member has 1 or 0 votes. + +- To select a member to be a "preferred primary", modify the member's + :ref:`priority value ` + instead of adjusting the number of votes the member has. + +.. TODO verify this. what should one do when >7 members are in a set? +- When there are more than seven members in a replica set, adjust the + number of votes for each active member. + Syncing ------- From 12c707ac5687a326e34603520c83e28098d68d6c Mon Sep 17 00:00:00 2001 From: Andrew Leung Date: Mon, 30 Jul 2012 15:49:13 -0400 Subject: [PATCH 3/5] adding in information from the wiki --- .../replication-architectures.txt | 6 ++-- source/core/replication-internals.txt | 30 +++++++------------ source/core/replication.txt | 8 ++--- source/reference/replica-configuration.txt | 9 ++++-- source/tutorial/expand-replica-set.txt | 9 ++++++ 5 files changed, 31 insertions(+), 31 deletions(-) diff --git a/source/administration/replication-architectures.txt b/source/administration/replication-architectures.txt index fbdb9724015..208ec773304 100644 --- a/source/administration/replication-architectures.txt +++ b/source/administration/replication-architectures.txt @@ -132,10 +132,10 @@ for these kinds of nodes: `.) - **Voting**: This changes the number of votes that a member of the - set node has in elections for primary. In general use priority to + replica set has in elections. In general, use priority to control the outcome of elections, as weighting votes introduces - operational complexities and risks set failure. Only modify the - number of votes, if you need to have more than 7 members of a + operational complexities and risks. Only modify the + number of votes when you need to have more than 7 members in a replica set. (:ref:`see also `.) .. note:: diff --git a/source/core/replication-internals.txt b/source/core/replication-internals.txt index 351664e4ec1..5d4a0378952 100644 --- a/source/core/replication-internals.txt +++ b/source/core/replication-internals.txt @@ -115,7 +115,7 @@ modify the configuration of an existing replica set. Elections --------- -When you initialize a replica set for the first time, and when any +When you initialize a replica set for the first time, or when any failover occurs, an election takes place to decide which member should become :term:`primary`. A primary is the only member in the replica set that can accept write commands such as :func:`insert() @@ -126,7 +126,7 @@ Elections are the process replica set members use to select the primary in a cluster. Elections follow two events: a primary that "steps down" or a :term:`secondary` that loses contact with a :term:`primary` member. All members have one vote -in an election, and every :program:`mongod` can veto an election. A +in an election, and any :program:`mongod` can veto an election. A single veto will invalidate the election. An existing primary will step down in response to the @@ -183,8 +183,10 @@ aware of the following conditions and possible situations: .. note:: - The only exception is that members with a priority of ``0`` cannot - become :term:`primary` and will not seek election. + The only exception is that members with a priority of ``0`` + cannot become :term:`primary` and will not seek election. See + :ref:`replica-set-node-priority-configuration` for more + information. - Replica set members cannot become primary *unless* they have the highest "optime" of any visible members in the set. @@ -194,23 +196,11 @@ aware of the following conditions and possible situations: :term:`primary` until the member with the highest priority catches up to the latest operation. -Each member in a replica set has only one vote, by default. You may -change the number of votes each member has to allow for larger replica -sets. Each replica set is limited to 12 total members with 7 voting -members. -- The number of votes is modifiable in the :data:`replica set configuration ` - -- The number of votes each member has can be any non-negative integer, - but it is highly recommended each member has 1 or 0 votes. - -- To select a member to be a "preferred primary", modify the member's - :ref:`priority value ` - instead of adjusting the number of votes the member has. - -.. TODO verify this. what should one do when >7 members are in a set? -- When there are more than seven members in a replica set, adjust the - number of votes for each active member. +.. seealso:: ":ref:`Non-voting members in a replica + set`", + ":ref:`replica-set-node-priority-configuration`", + ":data:`replica configuration ` Syncing ------- diff --git a/source/core/replication.txt b/source/core/replication.txt index 9c372403ced..be4ccd8d98e 100644 --- a/source/core/replication.txt +++ b/source/core/replication.txt @@ -170,11 +170,11 @@ participate in :term:`elections `. Non-Voting ~~~~~~~~~~ -You may choose to change the number of votes that each node has in +You may choose to change the number of votes that each member has in :term:`elections ` for :term:`primary`. In general, all -nodes should have only 1 vote to prevent intermittent ties, deadlock, +members should have only 1 vote to prevent intermittent ties, deadlock, or the wrong nodes from becoming :term:`primary`. Use ":ref:`replica -set priorities `" to control which nodes +set priorities `" to control which members are more likely to become primary. .. index:: pair: replica set; failover @@ -247,8 +247,6 @@ have a single vote in :ref:`elections `. :data:`members[n].votes` except to permit more than 7 secondary nodes. -.. COMMENT a bit unclear. ALWAYS set, but except to have more than 7 secondary? - .. seealso:: ":ref:`Node Priority Configuration `" .. index:: pair: replica set; consistency diff --git a/source/reference/replica-configuration.txt b/source/reference/replica-configuration.txt index 7f0758f9b9a..b783ba5965a 100644 --- a/source/reference/replica-configuration.txt +++ b/source/reference/replica-configuration.txt @@ -174,9 +174,12 @@ Configuration Variables **Default**: 1 Controls the number of votes a server has in a :ref:`replica set - election `. If you need more than 7 nodes, - use this setting to add additional non-voting nodes with a - :data:`members[n].votes` value of ``0``. + election `. The number of votes each member + has can be any non-negative integer, but it is highly recommended + each member has 1 or 0 votes. + + If you need more than 7 nodes, use this setting to add additional + non-voting nodes with a :data:`members[n].votes` value of ``0``. For most deployments and most members, use the default value, ``1``, for :data:`members[n].votes`. diff --git a/source/tutorial/expand-replica-set.txt b/source/tutorial/expand-replica-set.txt index 0f0df0b961c..9114cfea2b3 100644 --- a/source/tutorial/expand-replica-set.txt +++ b/source/tutorial/expand-replica-set.txt @@ -126,4 +126,13 @@ Production Notes :term:`primary` member's :term:`oplog`. The new secondary must be able to become current using operations from the primary's oplog. +- There is a maximum of seven :ref:`voting members + ` in any replica set. When adding + more members to a replica set that already has seven votes, you must + either: + - add the new member as a :ref:`non-voting members `. + + - remove votes from an :data:`existing member ` + + .. seealso:: :data:`Modifying member votes ` From d2866e6338a07c9cd0d8a3bfe25f687d55c87d89 Mon Sep 17 00:00:00 2001 From: Andrew Leung Date: Mon, 30 Jul 2012 16:06:03 -0400 Subject: [PATCH 4/5] fixing up errors --- source/core/replication-internals.txt | 14 +++++++------- source/reference/replica-configuration.txt | 4 ++-- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/source/core/replication-internals.txt b/source/core/replication-internals.txt index 5d4a0378952..8d022746450 100644 --- a/source/core/replication-internals.txt +++ b/source/core/replication-internals.txt @@ -31,9 +31,9 @@ exceptional situations may cause secondaries lag behind further. See Also consider :ref:`oplog sizing ` for more information about the oplog. -All nodes send heartbeats to all other nodes, and can import -operations to into its oplog from any other node in the -cluster. +All members send heartbeats to all other members, and can import +operations to into its oplog from any other member in the +set. .. In 2.0, replicas would import entries from the member lowest .. "ping," This wasn't true in 1.8 and will likely change in 2.2. @@ -115,15 +115,15 @@ modify the configuration of an existing replica set. Elections --------- -When you initialize a replica set for the first time, or when any +When you initialize a :term:`replica set` for the first time, or when any failover occurs, an election takes place to decide which member should become :term:`primary`. A primary is the only member in the replica -set that can accept write commands such as :func:`insert() +set that can accept write operations including :func:`insert() `, :func:`update() `, -and :func:`remove() `. Elections are the process replica set members use to -select the primary in a cluster. Elections follow two events: +select the primary in a set. Elections follow after one of two events: a primary that "steps down" or a :term:`secondary` that loses contact with a :term:`primary` member. All members have one vote in an election, and any :program:`mongod` can veto an election. A diff --git a/source/reference/replica-configuration.txt b/source/reference/replica-configuration.txt index b783ba5965a..1352aeae553 100644 --- a/source/reference/replica-configuration.txt +++ b/source/reference/replica-configuration.txt @@ -178,8 +178,8 @@ Configuration Variables has can be any non-negative integer, but it is highly recommended each member has 1 or 0 votes. - If you need more than 7 nodes, use this setting to add additional - non-voting nodes with a :data:`members[n].votes` value of ``0``. + If you need more than 7 members, use this setting to add additional + non-voting members with a :data:`members[n].votes` value of ``0``. For most deployments and most members, use the default value, ``1``, for :data:`members[n].votes`. From 99cf89b314359e4c2facd18ea64c445b8f29a736 Mon Sep 17 00:00:00 2001 From: Andrew Leung Date: Mon, 30 Jul 2012 16:15:03 -0400 Subject: [PATCH 5/5] touching up more... --- source/core/replication-internals.txt | 2 +- source/tutorial/expand-replica-set.txt | 7 +++---- 2 files changed, 4 insertions(+), 5 deletions(-) diff --git a/source/core/replication-internals.txt b/source/core/replication-internals.txt index 8d022746450..e2844715495 100644 --- a/source/core/replication-internals.txt +++ b/source/core/replication-internals.txt @@ -199,7 +199,7 @@ aware of the following conditions and possible situations: .. seealso:: ":ref:`Non-voting members in a replica set`", - ":ref:`replica-set-node-priority-configuration`", + ":ref:`replica-set-node-priority-configuration`", and ":data:`replica configuration ` Syncing diff --git a/source/tutorial/expand-replica-set.txt b/source/tutorial/expand-replica-set.txt index 9114cfea2b3..36804967bf1 100644 --- a/source/tutorial/expand-replica-set.txt +++ b/source/tutorial/expand-replica-set.txt @@ -131,8 +131,7 @@ Production Notes more members to a replica set that already has seven votes, you must either: - - add the new member as a :ref:`non-voting members `. + - add the new member as a :ref:`non-voting members + ` or, - - remove votes from an :data:`existing member ` - - .. seealso:: :data:`Modifying member votes ` + - remove votes from an :data:`existing member `.