[Backport] DOCS-14446: Add rs.reconfigForPSASet() (#3174)

* DOCS-14446: Add rs.reconfigForPSASet()

* change release version

---------

Co-authored-by: Naomi Pentrel <[email protected]>

Author: jeff-allen-mongo

source/reference/method/js-replication.txt

@@ -60,7 +60,13 @@ Replication Methods
 
    * - :method:`rs.reconfig()`
 
-     - Re-configures a replica set by applying a new replica set configuration object.
+     - Reconfigures a replica set by applying a new replica set configuration object.
+
+   * - :method:`rs.reconfigForPSASet()`
+
+     - Safely perform some reconfiguration changes on a
+       primary-secondary-arbiter (PSA) replica set or on a replica set that
+       is changing to a PSA architecture.
 
    * - :method:`rs.remove()`
 
@@ -84,8 +90,8 @@ Replication Methods
 
 
 .. toctree::
-   :titlesonly: 
-   :hidden: 
+   :titlesonly:
+   :hidden:
 
    /reference/method/rs.add
    /reference/method/rs.addArb
@@ -97,6 +103,7 @@ Replication Methods
    /reference/method/rs.printSecondaryReplicationInfo
    /reference/method/rs.printSlaveReplicationInfo
    /reference/method/rs.reconfig
+   /reference/method/rs.reconfigForPSASet
    /reference/method/rs.remove
    /reference/method/rs.secondaryOk
    /reference/method/rs.status

source/reference/method/rs.reconfigForPSASet.txt

@@ -0,0 +1,312 @@
+======================
+rs.reconfigForPSASet()
+======================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+
+.. method:: rs.reconfigForPSASet( memberIndex, config, { options } )
+
+   .. versionadded:: 4.4.11
+
+   Safely perform some reconfiguration changes on a
+   primary-secondary-arbiter (PSA) replica set or on a replica set that
+   is changing to a PSA architecture. You should only use this method in
+   one of the following cases:
+
+   - You want to reconfigure a secondary in an existing three-member
+     replica set with a PSA architecture to become a voting,
+     data-bearing node with a non-zero :rsconf:`priority
+     <members[n].priority>`.
+   - You want to add a new voting, data-bearing node with a non-zero
+     priority to an existing two-member replica set that contains one
+     voting, data-bearing node and one arbiter.
+
+   .. warning::
+
+      If the secondary you are adding is lagged and the resulting
+      replica set is a PSA configuration, the first configuration change
+      will change the number of nodes that need to commit a change with
+      :writeconcern:`"majority"`. In this case, your commit point will
+      lag until the secondary has caught up.
+
+   For details about the behavior of this method, see
+   :ref:`reconfigForPSASet-behavior`.
+
+Syntax
+------
+
+The :method:`rs.reconfigForPSASet()` method has the following syntax:
+
+.. code-block:: bash
+
+   rs.reconfigForPSASet(
+     memberIndex: <num>,
+     config: <configuration>,
+     {
+       "force" : <boolean>,
+       "maxTimeMS" : <int>
+     }
+   )
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 20 80
+
+   * - Parameter
+
+     - Type
+
+     - Description
+
+   * - ``memberIndex``
+
+     - integer
+
+     - The index of the secondary that is being added or modified.
+
+   * - ``config``
+
+     - document
+
+     - A :doc:`document </reference/replica-configuration>` that
+       specifies the new configuration of a replica set.
+
+   * - ``force``
+
+     - boolean
+
+     - *Optional*
+
+       .. warning::
+
+          Running the :method:`rs.reconfigForPSASet()` method with
+          ``force: true`` is not recommended and can lead to
+          committed writes being rolled back.
+
+       Specify ``true`` to force the available replica set members to
+       accept the new configuration. Defaults to ``false``.
+
+       Force reconfiguration can result in unexpected or undesired
+       behavior, including :ref:`rollback <replica-set-rollbacks>` of
+       :writeconcern:`"majority"` committed writes.
+
+   * - ``maxTimeMS``
+
+     - integer
+
+     - *Optional*
+
+       Specifies a cumulative time limit in milliseconds
+       for processing each reconfiguration during the
+       :method:`rs.reconfigForPSASet()` operation. By default,
+       :method:`rs.reconfigForPSASet()` waits indefinitely for the
+       replica configurations to propagate to a majority of replica
+       set members.
+
+.. _reconfigForPSASet-behavior:
+
+Behavior
+--------
+
+The :method:`rs.reconfigForPSASet()` method reconfigures your replica
+set in two steps:
+
+1. The method reconfigures your replica set to add or modify a secondary
+   with  ``{ votes: 1, priority: 0 }``.
+2. Once the added or modified secondary has caught up with all committed
+   writes, the method reconfigures the secondary to have the
+   :rsconf:`priority <members[n].priority>` specified in the
+   :method:`rs.reconfigForPSASet()` command
+   (``{ votes: 1, priority: <num> }``).
+
+The two-step approach avoids the possibility of rolling back committed
+writes in the case of a failover to the new secondary before the new
+secondary has all committed writes from the previous configuration.
+
+.. _reconfigForPSASet-usage:
+
+Example
+-------
+
+A replica set named ``rs0`` has the following configuration:
+
+.. code-block:: javascript
+
+   {
+      "_id" : "rs0",
+      "version" : 1,
+      "term": 1,
+      "members" : [
+         {
+            "_id" : 0,
+            "host" : "mongodb0.example.net:27017",
+            "arbiterOnly" : false,
+            "buildIndexes" : true,
+            "hidden" : false,
+            "priority" : 1,
+            "tags" : {},
+            "secondaryDelaySecs" : Long("0"),
+            "votes" : 1
+         },
+         {
+            "_id" : 2,
+            "host" : "mongodb2.example.net:27017",
+            "arbiterOnly" : true,
+            "buildIndexes" : true,
+            "hidden" : false,
+            "priority" : 0,
+            "tags" : {},
+            "secondaryDelaySecs" : Long("0"),
+            "votes" : 1
+         }
+      ],
+      "protocolVersion" : Long("1"),
+      "writeConcernMajorityJournalDefault": true,
+      "settings" : {
+         "chainingAllowed" : true,
+         "heartbeatIntervalMillis" : 2000,
+         "heartbeatTimeoutSecs" : 10,
+         "electionTimeoutMillis" : 10000,
+         "catchUpTimeoutMillis" : 2000,
+         "getLastErrorModes" : {},
+         "getLastErrorDefaults" : {
+            "w" : 1,
+            "wtimeout" : 0
+         },
+         "replicaSetId" : ObjectId("60e6f83923193faa336889d2")
+      }
+   }
+
+The following sequence of operations add a new secondary to the replica
+set. The operations are issued in the :mongosh:`mongosh </>` shell while
+connected to the primary.
+
+.. code-block:: javascript
+
+   cfg = rs.conf();
+   cfg["members"] = [
+     {
+        "_id" : 0,
+        "host" : "mongodb0.example.net:27017",
+        "arbiterOnly" : false,
+        "buildIndexes" : true,
+        "hidden" : false,
+        "priority" : 1,
+        "tags" : {},
+        "secondaryDelaySecs" : Long("0"),
+        "votes" : 1
+     },
+     {
+        "_id" : 1,
+        "host" : "mongodb2.example.net:27017",
+        "arbiterOnly" : false,
+        "buildIndexes" : true,
+        "hidden" : false,
+        "priority" : 2,
+        "tags" : {},
+        "secondaryDelaySecs" : Long("0"),
+        "votes" : 1
+     },
+     {
+        "_id" : 2,
+        "host" : "mongodb2.example.net:27017",
+        "arbiterOnly" : true,
+        "buildIndexes" : true,
+        "hidden" : false,
+        "priority" : 0,
+        "tags" : {},
+        "secondaryDelaySecs" : Long("0"),
+        "votes" : 1
+     }
+   ]
+   rs.reconfigForPSASet(1, cfg);
+
+#. The first statement uses the :method:`rs.conf()` method to retrieve
+   a document containing the current :ref:`configuration
+   <replSetGetConfig-output>` for the replica set and stores the
+   document in the local variable ``cfg``.
+
+#. The second statement adds the new secondary to the ``members`` array.
+   In this configuration the new secondary is added at ``memberIndex``
+   ``1``. The ``memberIndex`` is the same as the array index. For
+   additional settings, see :ref:`replica set configuration settings
+   <replSetGetConfig-output>`.
+
+#. The last statement calls the :method:`rs.reconfigForPSASet()` method
+   with the ``memberIndex`` ``1`` and the modified ``cfg``. The
+   ``memberIndex`` is the array position of the new member in the
+   ``members`` array. Upon successful reconfiguration, the replica set
+   configuration resembles the following:
+
+   .. code-block:: javascript
+
+      {
+         "_id" : "rs0",
+         "version" : 1,
+         "term": 1,
+         "members" : [
+            {
+               "_id" : 0,
+               "host" : "mongodb0.example.net:27017",
+               "arbiterOnly" : false,
+               "buildIndexes" : true,
+               "hidden" : false,
+               "priority" : 1,
+               "tags" : {},
+               "secondaryDelaySecs" : Long("0"),
+               "votes" : 1
+            },
+            {
+               "_id" : 1,
+               "host" : "mongodb2.example.net:27017",
+               "arbiterOnly" : false,
+               "buildIndexes" : true,
+               "hidden" : false,
+               "priority" : 2,
+               "tags" : {},
+               "secondaryDelaySecs" : Long("0"),
+               "votes" : 1
+            },
+            {
+               "_id" : 2,
+               "host" : "mongodb2.example.net:27017",
+               "arbiterOnly" : true,
+               "buildIndexes" : true,
+               "hidden" : false,
+               "priority" : 0,
+               "tags" : {},
+               "secondaryDelaySecs" : Long("0"),
+               "votes" : 1
+            }
+         ],
+         "protocolVersion" : Long("1"),
+         "writeConcernMajorityJournalDefault": true,
+         "settings" : {
+            "chainingAllowed" : true,
+            "heartbeatIntervalMillis" : 2000,
+            "heartbeatTimeoutSecs" : 10,
+            "electionTimeoutMillis" : 10000,
+            "catchUpTimeoutMillis" : 2000,
+            "getLastErrorModes" : {},
+            "getLastErrorDefaults" : {
+               "w" : 1,
+               "wtimeout" : 0
+            },
+            "replicaSetId" : ObjectId("60e6f83923193faa336889d2")
+         }
+      }
+
+.. seealso::
+
+   - :method:`rs.conf()`
+   - :method:`rs.reconfig()`
+   - :ref:`replSetGetConfig-output`
+   - :doc:`/administration/replica-set-member-configuration`
+   - :doc:`/administration/replica-set-maintenance`