DOCS-260 migrating rs design concepts, draft 1

Author: Bob Grabar

source/administration/replica-sets.txt

@@ -46,11 +46,16 @@ configurations.
 .. warning::
 
    The :method:`rs.reconfig()` shell command can force the current
-   primary to step down, which causes an election. When the primary
+   primary to step down, which causes an :ref:`election <replica-set-elections>`. When the primary
    steps down, the :program:`mongod` closes all client
    connections. While, this typically takes 10-20 seconds, attempt to
    make these changes during scheduled maintenance periods.
 
+.. seealso::
+
+   - The :ref:`replica-set-elections` topic in the :doc:`/core/replication` document
+   - The :ref:`replica-set-election-internals` topic in the :doc:`/core/replication-internals` document
+
 .. index:: replica set members; secondary only
 .. _replica-set-secondary-only-members:
 .. _replica-set-secondary-only-configuration:
@@ -69,9 +74,10 @@ these members from ever becoming primary.
 
 To configure a member as secondary-only, set its
 :data:`members[n].priority` value to ``0``. Any member with a
-:data:`members[n].priority` equal to ``0`` will never seek election and
-cannot become primary in any situation. For more information on priority
-levels, see :ref:`replica-set-node-priority`.
+:data:`members[n].priority` equal to ``0`` will never seek
+:ref:`election <replica-set-elections>` and cannot become primary in any
+situation. For more information on priority levels, see
+:ref:`replica-set-node-priority`.
 
 As an example of modifying member priorities, assume a four-member
 replica set with member ``_id`` values of: ``0``, ``1``, ``2``, and
@@ -107,10 +113,10 @@ This sets the following:
    If your replica set has an even number of members, add an
    :ref:`arbiter <replica-set-arbiters>` to ensure that
    members can quickly obtain a majority of votes in an
-   :ref:`election <replica-set-elections>` for primary.
+   election for primary.
 
 .. seealso:: :data:`members[n].priority` and :ref:`Replica Set
-   Reconfiguration <replica-set-reconfiguration-usage>`.
+   Reconfiguration <replica-set-reconfiguration-usage>`
 
 .. index:: replica set members; hidden
 .. _replica-set-hidden-members:
@@ -183,8 +189,8 @@ the amount of slave delay to apply:
 
 - The size of the oplog is sufficient to capture *more than* the
   number of operations that typically occur in that period of
-  time. See the section on :ref:`oplog sizing
-  <replica-set-oplog-sizing>` for more information.
+  time. For more information on oplog size, see the
+  :ref:`replica-set-oplog-sizing` topic in the :doc:`/core/replication` document.
 
 Delayed members must have a :term:`priority` set to ``0`` to prevent
 them from becoming primary in their replica sets. Also these members
@@ -233,7 +239,7 @@ Arbiters
 
 Arbiters are special :program:`mongod` instances that do not hold a
 copy of the data and thus cannot become primary. Arbiters exist solely
-participate in :term:`elections <election>`.
+participate in :ref:`elections <replica-set-elections>`.
 
 .. note::
 
@@ -290,15 +296,14 @@ Non-Voting
 ~~~~~~~~~~
 
 You may choose to change the number of votes that each member has in
-:term:`elections <election>` for :term:`primary`. In general, all
+:ref:`elections <replica-set-elections>` for :term:`primary`. In general, all
 members should have only 1 vote to prevent intermittent ties, deadlock,
 or the wrong members from becoming :term:`primary`. Use :ref:`replica
 set priorities <replica-set-node-priority>` to control which members
 are more likely to become primary.
 
-To disable a member's ability to vote in :ref:`elections
-<replica-set-elections>` use the following command sequence in the
-:program:`mongo` shell.
+To disable a member's ability to vote in elections, use the following
+command sequence in the :program:`mongo` shell.
 
 .. code-block:: javascript
 
@@ -454,7 +459,7 @@ number. :method:`rs.reconfig()` will not change the value of
 .. warning::
 
    Any replica set configuration change can trigger the current
-   :term:`primary` to step down, which forces an :term:`election`. This
+   :term:`primary` to step down, which forces an :ref:`election <replica-set-elections>`. This
    causes the current shell session, and clients connected to this replica set,
    to produce an error even when the operation succeeds.
 
@@ -486,7 +491,7 @@ the new configuration.
 
 If a member has :data:`members[n].priority` set to ``0``, it is
 ineligible to become :term:`primary` and will not seek
-elections. :ref:`Hidden members <replica-set-hidden-members>`,
+election. :ref:`Hidden members <replica-set-hidden-members>`,
 :ref:`delayed members <replica-set-delayed-members>`, and
 :ref:`arbiters <replica-set-arbiters>` all have :data:`members[n].priority`
 set to ``0``.
@@ -741,4 +746,7 @@ data to a :term:`BSON` file that you can view using
 You can prevent rollbacks by ensuring safe writes by using
 the appropriate :term:`write concern`.
 
-.. seealso:: :ref:`Replica Set Elections <replica-set-elections>`
+.. seealso::
+
+   - The :ref:`replica-set-elections` topic in the :doc:`/core/replication` document
+   - The :ref:`replica-set-election-internals` topic in the :doc:`/core/replication-internals` document

source/core/replication-internals.txt

@@ -18,17 +18,15 @@ troubleshooting and for further understanding MongoDB's behavior and approach.
 Oplog
 -----
 
-Replication itself works by way of a special :term:`capped collection`
-called the :term:`oplog`. This collection keeps a rolling record of
-all operations applied to the :term:`primary`. Secondary members then
-replicate this log by applying the operations to themselves in an
-asynchronous process.  Under normal operation, :term:`secondary` members
-reflect writes within one second of the primary. However, various
-exceptional situations may cause secondaries to lag behind further. See
+Under normal operation, MongoDB updates the :ref:`oplog
+<replica-set-oplog-sizing>` on a :term:`secondary` within one second of
+applying an operation to a :ref:`primary`. However, various exceptional
+situations may cause a secondary to lag further behind. See
 :ref:`Replication Lag <replica-set-replication-lag>` for details.
 
-All members send heartbeats (pings) to all other members in the set and can
-import operations to the local oplog from any other member in the set.
+All members of a :term:`replica set` send heartbeats (pings) to all
+other members in the set and can import operations to the local oplog
+from any other member in the set.
 
 Replica set oplog operations are :term:`idempotent`. The following
 operations require idempotency:
@@ -37,9 +35,6 @@ operations require idempotency:
 - post-rollback catch-up
 - sharding chunk migrations
 
-.. seealso:: The :ref:`replica-set-oplog-sizing` topic in
-   :doc:`/core/replication`.
-
 .. TODO Verify that "sharding chunk migrations" (above) requires
    idempotency. The wiki was unclear on the subject.
 
@@ -48,9 +43,12 @@ operations require idempotency:
 
 .. _replica-set-implementation:
 
-Implementation
+Data Integrity
 --------------
 
+Read Preferences
+~~~~~~~~~~~~~~~~
+
 MongoDB uses :term:`single-master replication` to ensure that the
 database remains consistent. However, clients may modify the
 :ref:`read preferences <replica-set-read-preference>` on a
@@ -71,6 +69,13 @@ section for more about :ref:`read preference
    output to asses the current state of replication and determine if
    there is any unintended replication delay.
 
+
+
+
+
+Elections for Primary
+~~~~~~~~~~~~~~~~~~~~~
+
 In the default configuration, all members have an equal chance of
 becoming primary; however, it's possible to set :data:`priority <members[n].priority>` values that
 weight the election. In some architectures, there may be operational
@@ -80,6 +85,12 @@ center should *not* become primary. See: :ref:`node
 priority <replica-set-node-priority>` for more background on this
 concept.
 
+
+
+
+Configurations that Affect Membership Behavior
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 Replica sets can also include members with the following four special
 configurations that affect membership behavior:
 
@@ -115,26 +126,33 @@ administration. In particular use the :method:`rs.conf()` to return a
 </reference/replica-configuration>` and use :method:`rs.reconfig()` to
 modify the configuration of an existing replica set.
 
+
+
+
+
+
 .. index:: replica set; elections
 .. index:: replica set; failover
 .. _replica-set-election-internals:
 
 Elections
 ---------
 
-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
+Elections are the process :term:`replica set` members use to select which member should
 become :term:`primary`. A primary is the only member in the replica
 set that can accept write operations, including :method:`insert()
 <db.collection.insert()>`, :method:`update() <db.collection.update()>`,
 and :method:`remove() <db.collection.remove()>`.
 
-Elections are the process replica set members use to
-select the primary in a set. Two types of events can trigger an election:
-a primary steps down or a :term:`secondary` member
-loses contact with a primary. All members have one vote
-in an election, and any :program:`mongod` can veto an election. A
-single veto invalidates the election.
+The following events can trigger an election:
+
+- You initialize a replica set for the first time.
+
+- A primary steps down.
+
+- A :term:`secondary` member loses contact with a primary.
+
+- A failover occurs.
 
 An existing primary will step down in response to the
 :dbcommand:`replSetStepDown` command or if it sees that one of
@@ -146,11 +164,13 @@ set. When the current primary steps down, it closes all open client
 connections to prevent clients from unknowingly writing data to a
 non-primary member.
 
-In an election, every member, including :ref:`hidden
-<replica-set-hidden-members>` members, :ref:`arbiters
-<replica-set-arbiters>`, and even recovering members, get a single
-vote. Members will give votes to every eligible member that calls an
-election.
+In an election, all members have one vote,
+including :ref:`hidden <replica-set-hidden-members>` members, :ref:`arbiters
+<replica-set-arbiters>`, and even recovering members.
+Any :program:`mongod` can veto an election.
+
+Any member of a replica set can veto an election, even if the
+member is a :ref:`non-voting member <replica-set-non-voting-members>`.
 
 A member of the set will veto an election under the following
 conditions:
@@ -167,15 +187,10 @@ conditions:
   (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
+- The current primary will veto an election if it has the same or
   more recent operations (i.e. a "higher or equal optime") than the
   member seeking election.
 
-.. note::
-
-   Any member of a replica set *can* veto an election, even if the
-   member is a :ref:`non-voting member <replica-set-non-voting-members>`.
-
 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:
@@ -186,15 +201,9 @@ aware of the following conditions and possible situations:
 
 - Replica set members compare priorities only with other members of
   the set. The absolute value of priorities does not have any impact on
-  the outcome of replica set elections.
-
-  .. note::
-
-     The only exception is that members with :data:`priority
-     <members[n].priority>` values of ``0``
-     cannot become primary and will not seek election. See
-     :ref:`replica-set-node-priority-configuration` for more
-     information.
+  the outcome of replica set elections, with the exception of the value ``0``,
+  which indicates the member cannot become primary and cannot seek election.
+  For details, see :ref:`replica-set-node-priority-configuration`.
 
 - A replica set member cannot become primary *unless* it has the
   highest "optime" of any visible member in the set.
@@ -204,12 +213,31 @@ aware of the following conditions and possible situations:
   primary until the member with the highest priority catches up
   to the latest operation.
 
-
 .. seealso:: :ref:`Non-voting members in a replica
    set <replica-set-non-voting-members>`,
    :ref:`replica-set-node-priority-configuration`, and
    :data:`replica configuration <members[n].votes>`.
 
+
+Elections and Network Partitions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A replica set has at most one primary at a given time. If a majority of
+the set is up, the most up-to-date secondary will be elected primary. If
+a majority of the set is not up or reachable, no member will be elected
+primary.
+
+There is no way to tell (from the set's point of view) the difference
+between a network partition and nodes going down, so members left in a
+minority will not attempt to become primary (to prevent a set from
+ending up with primaries on either side of a partition).
+
+This means that, if there is no majority on either side of a network
+partition, the set will be read only. Thus, we suggest an odd number of
+servers: e.g., two servers in one data center and one in another. The
+upshot of this strategy is that data is consistent: there are no
+multi-primary conflicts to resolve.
+
 Syncing
 -------