DOCS-13526: set initial sync source via initialSyncSourceReadPreference

ravindk89 · ravindk89 · commit 9d18a451e41e · 2020-04-30T17:12:05.000-04:00
diff --git a/source/core/replica-set-sync.txt b/source/core/replica-set-sync.txt
@@ -25,7 +25,13 @@ Initial Sync
 ------------
 
 Initial sync copies all the data from one member of the replica set to
-another member.
+another member. See :ref:`replica-set-initial-sync-source-selection` for
+more information on initial sync source selection criteria.
+
+Starting in MongoDB 4.4, you can specify the preferred initial sync
+source using the :parameter:`initialSyncSourceReadPreference` parameter.
+This parameter can only be specified when starting the
+:binary:`~bin.mongod`.
 
 Process
 ~~~~~~~
@@ -87,6 +93,107 @@ synchronization process from the beginning.
 The secondary attempts to restart the initial sync up to ``10`` times
 before returning a fatal error.
 
+.. _replica-set-initial-sync-source-selection:
+
+Initial Sync Source Selection
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Initial sync source selection depends on the value of the
+:binary:`~bin.mongod` startup parameter
+:parameter:`initialSyncSourceReadPreference` (*new in 4.4*):
+
+- For :parameter:`initialSyncSourceReadPreference` set to
+  :readmode:`primary` (default if :rsconf:`chaining
+  <settings.chainingAllowed>` is disabled), select the :term:`primary`
+  as the sync source. If the primary is unavailable or unreachable, log
+  an error and periodically check for primary availability.
+
+- For :parameter:`initialSyncSourceReadPreference` set to
+  :readmode:`primaryPreferred` (default for voting replica set
+  members), attempt to select the :term:`primary` as the sync source. If
+  the primary is unavailable or unreachable, perform sync source
+  selection from the remaining replica set members.
+
+- For all other supported read modes, perform sync source selection 
+  from the replica set members.
+
+Members performing initial sync source selection make two passes through 
+the list of all replica set members:
+
+.. tabs::
+
+   .. tab:: Sync Source Selection (First Pass)
+      :tabid: firstpass
+
+      The member applies the following criteria to each replica 
+      set member when making the first pass for selecting a
+      initial sync source:
+
+      - The sync source *must* be in the :replstate:`PRIMARY` or
+        :replstate:`SECONDARY` replication state.
+
+      - The sync source *must* be online and reachable.
+
+      - If :parameter:`initialSyncSourceReadPreference` is
+        :readmode:`secondary` or :readmode:`secondaryPreferred`, 
+        the sync source *must* be a :term:`secondary`.
+
+      - The sync source *must* be :rsconf:`visible <members[n].hidden>`.
+
+      - The sync source *must* be within ``30`` seconds of the newest 
+        oplog entry on the primary.
+
+      - If the member :rsconf:`builds indexes
+        <members[n].buildIndexes>`, the sync source *must*
+        build indexes.
+
+      - If the member :rsconf:`votes <members[n].votes>` in 
+        replica set elections, the sync source *must* also vote.
+
+      - If the member is *not* a :rsconf:`delayed member
+        <members[n].slaveDelay>`, the sync source *must not* be delayed.
+
+      - If the member *is* a :rsconf:`delayed member
+        <members[n].slaveDelay>`, the sync source must have a shorter 
+        configured delay.
+
+      - The sync source *must* be faster (i.e. lower latency) than 
+        the current best sync source.
+
+      If no candidate sync sources remain after the first pass, 
+      the member performs a second pass with relaxed criteria. 
+      See :guilabel:`Sync Source Selection (Second Pass)`.
+
+   .. tab:: Sync Source Selection (Second Pass)
+      :tabid: second pass
+
+      The member applies the following criteria to each replica 
+      set member when making the second pass for selecting a
+      initial sync source:
+
+      - The sync source *must* be in the 
+        :replstate:`PRIMARY` or :replstate:`SECONDARY` replication 
+        state.
+
+      - The sync source *must* be online and reachable.
+
+      - If :parameter:`initialSyncSourceReadPreference` is
+        :readmode:`secondary`, the sync source *must* be a
+        :term:`secondary`.
+
+      - If the member :rsconf:`builds indexes
+        <members[n].buildIndexes>`, the sync source must
+        build indexes.
+
+      - The sync source *must* be faster (i.e. lower latency) than 
+        the current best sync source.
+       
+If the member cannot select an initial sync source after two passes, it
+logs an error and waits ``1`` second before restarting the selection
+process. The secondary :binary:`~bin.mongod` can restart the initial
+sync source selection process up to ``10`` times before exiting with an
+error.
+
 .. _replica-set-replication:
 
 Replication
@@ -99,21 +206,8 @@ process. [#slow-oplogs]_
 
 Secondaries may automatically change their *sync from* source as needed
 based on changes in the ping time and state of other members'
-replication.
-
-.. versionchanged:: 3.2
-
-   .. include:: /includes/fact-voting-node-sync-incompatibility.rst
-
-Secondaries avoid syncing from
-:ref:`delayed members <replica-set-delayed-members>` and :ref:`hidden
-members <replica-set-hidden-members>`.
-
-If a secondary member has :rsconf:`members[n].buildIndexes` set to ``true``,
-it can only sync from other members where :rsconf:`~members[n].buildIndexes`
-is ``true``. Members where :rsconf:`~members[n].buildIndexes` is ``false`` can
-sync from any other member, barring other sync restrictions.
-:rsconf:`~members[n].buildIndexes` is ``true`` by default.
+replication. See :ref:`replica-set-replication-sync-source-selection`
+for more information on sync source selection criteria.
 
 .. [#slow-oplogs]
 
@@ -151,3 +245,100 @@ Flow Control
 .. include:: /includes/extracts/4.2-changes-flow-control-general-desc.rst
 
 For more information, see :ref:`flow-control`.
+
+.. _replica-set-replication-sync-source-selection:
+
+Replication Sync Source Selection
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Replication sync source selection depends on the replica set 
+:rsconf:`chaining <settings.chainingAllowed>` setting:
+
+- With chaining enabled (default), perform sync source selection from
+  the replica set members.
+
+- With chaining disabled, select the :term:`primary` as the sync 
+  source. If the primary is unavailable or unreachable, log an 
+  error and periodically check for primary availability.
+
+Members performing replication sync source selection make two passes
+through the list of all replica set members:
+
+.. tabs::
+
+   .. tab:: Sync Source Selection (First Pass)
+      :tabid: firstpass
+
+      The member applies the following criteria to each replica 
+      set member when making the first pass for selecting a
+      replication sync source:
+
+      - The sync source *must* be in the :replstate:`PRIMARY` or
+        :replstate:`SECONDARY` replication state.
+
+      - The sync source *must* be online and reachable.
+
+      - The sync source *must* have newer oplog entries than the member
+        (i.e. the sync source is *ahead* of the member).
+
+      - The sync source *must* be :rsconf:`visible <members[n].hidden>`.
+
+      - The sync source *must* be within ``30`` seconds of the newest 
+        oplog entry on the primary.
+
+      - If the member :rsconf:`builds indexes
+        <members[n].buildIndexes>`, the sync source *must*
+        build indexes.
+
+      - If the member :rsconf:`votes <members[n].votes>` in 
+        replica set elections, the sync source *must* also vote.
+
+      - If the member is *not* a :rsconf:`delayed member
+        <members[n].slaveDelay>`, the sync source *must not* be delayed.
+
+      - If the member *is* a :rsconf:`delayed member
+        <members[n].slaveDelay>`, the sync source must have a shorter 
+        configured delay.
+
+      - The sync source *must* be faster (i.e. lower latency) than 
+        the current best sync source.
+
+      If no candidate sync sources remain after the first pass, 
+      the member performs a second pass with relaxed criteria. 
+      See the :guilabel:`Sync Source Selection (Second Pass)`.
+
+   .. tab:: Sync Source Selection (Second Pass)
+      :tabid: second pass
+     
+      The member applies the following criteria to each replica 
+      set member when making the second pass for selecting a
+      replication sync source:
+
+      - The sync source *must* be in the 
+        :replstate:`PRIMARY` or :replstate:`SECONDARY` replication 
+        state.
+
+      - The sync source *must* be online and reachable.
+
+      - If the member :rsconf:`builds indexes
+        <members[n].buildIndexes>`, the sync source must
+        build indexes.
+       
+      - The sync source *must* be faster (i.e. lower latency) than 
+        the current best sync source.
+
+If the member cannot select a sync source after two passes, it logs an
+error and waits ``1`` second before restarting the selection process. 
+
+.. note::
+
+   Starting in MongoDB 4.4, the startup parameter
+   :parameter:`initialSyncSourceReadPreference` takes precedence over
+   the replica set's :rsconf:`settings.chainingAllowed` setting when
+   selecting an initial sync source. After a replica set member
+   successfully performs initial sync, it defers to the value of
+   :rsconf:`~settings.chainingAllowed` when selecting a replication sync
+   source.
+
+   See :ref:`replica-set-initial-sync-source-selection` for more
+   information on initial sync source selection.
diff --git a/source/reference/parameters.txt b/source/reference/parameters.txt
@@ -1973,6 +1973,51 @@ Replication Parameters
    attempts to resume the process if interrupted by a transient 
    network error. The default value is equivalent to 24 hours.
 
+.. parameter:: initialSyncSourceReadPreference
+
+   .. versionadded:: 4.4
+
+   *Type*: String
+
+   |mongod-only| 
+
+   The preferred source for performing :ref:`initial sync
+   <replica-set-initial-sync>`. Specify one of the following read
+   preference modes:
+
+   - :readmode:`primary`
+   - :readmode:`primaryPreferred` (Default for voting replica set members)
+   - :readmode:`secondary`
+   - :readmode:`secondaryPreferred`
+   - :readmode:`nearest` (Default for newly added *or* non-voting replica set members)
+
+   If the replica set has disabled :rsconf:`chaining
+   <settings.chainingAllowed>`, the default
+   :parameter:`initialSyncSourceReadPreference` read preference mode 
+   is :readmode:`primary`.
+
+   You cannot specify a tag set or ``maxStalenessSeconds`` to 
+   :parameter:`initialSyncSourceReadPreference`.
+
+   If the :binary:`~bin.mongod` cannot find a sync source based on the
+   specified read preference, it logs an error and restarts the initial
+   sync process. The :binary:`~bin.mongod` exits with an error if it
+   cannot complete the initial sync process after ``10`` attempts. For
+   more information on sync source selection, see
+   :ref:`replica-set-initial-sync-source-selection`.
+
+   :parameter:`initialSyncSourceReadPreference` takes precedence over
+   the replica set's :rsconf:`settings.chainingAllowed` setting when
+   selecting an initial sync source. After a replica set member
+   successfully completes initial sync, it defers to the value of
+   :rsconf:`~settings.chainingAllowed` when selecting a replication sync
+   source.
+
+   You can only set this parameter on startup, using either the 
+   :setting:`setParameter`
+   configuration file setting or the 
+   :option:`--setParameter <mongod --setParameter>` command line option.
+
 .. parameter:: oplogInitialFindMaxSeconds
 
    .. versionadded:: 3.6
diff --git a/source/release-notes/4.4.txt b/source/release-notes/4.4.txt
@@ -246,6 +246,34 @@ Safe Replica Set Reconfiguration
 .. |moreinfo| replace:: For more information, see the
    :ref:`replSetGetConfig <replSetGetConfig-commitmentStatus>` command.
 
+Preferred Initial Sync Source
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Starting in MongoDB 4.4, you can specify the preferred initial sync
+source using the :parameter:`initialSyncSourceReadPreference` parameter.
+You can only set this parameter on :binary:`~bin.mongod` startup, using
+either the :setting:`setParameter` configuration file setting or the
+:option:`--setParameter <mongod --setParameter>` command line option.
+
+:parameter:`initialSyncSourceReadPreference` supports following read
+preference modes:
+
+- :readmode:`primary`
+- :readmode:`primaryPreferred` (Default for voting replica set members)
+- :readmode:`secondary`
+- :readmode:`secondaryPreferred`
+- :readmode:`nearest` (Default for newly added *or* non-voting replica set members)
+
+If the replica set has disabled :rsconf:`chaining
+<settings.chainingAllowed>`, the default
+:parameter:`initialSyncSourceReadPreference` read preference mode 
+is :readmode:`primary`.
+
+You cannot specify a tag set or ``maxStalenessSeconds`` to
+:parameter:`initialSyncSourceReadPreference`.
+
+.. seealso:: :ref:`replica-set-initial-sync-source-selection`
+
 Sharded Clusters
 ----------------
 
