DOCS-14598: Add manual process for psa rs changes

Author: npentrel

source/administration/replica-set-maintenance.txt

@@ -49,13 +49,17 @@ replica sets.
 :doc:`/tutorial/configure-replica-set-secondary-sync-target`
    Specify the member that a secondary member synchronizes from.
 
-   :doc:`/tutorial/rename-unsharded-replica-set`
-      Rename an unsharded replica set.
+:doc:`/tutorial/rename-unsharded-replica-set`
+  Rename an unsharded replica set.
 
+:doc:`/tutorial/modify-psa-replica-set-safely`
+  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.
 
 .. toctree::
-   :titlesonly: 
-   :hidden: 
+   :titlesonly:
+   :hidden:
 
    /tutorial/change-oplog-size
    /tutorial/perform-maintence-on-replica-set-members
@@ -67,3 +71,4 @@ replica sets.
    /tutorial/change-hostnames-in-a-replica-set
    /tutorial/configure-replica-set-secondary-sync-target
    /tutorial/rename-unsharded-replica-set
+   /tutorial/modify-psa-replica-set-safely

source/includes/steps-modify-psa-replica-set-safely.yaml

@@ -0,0 +1,75 @@
+title: Add or modify a secondary with votes 1 but priority 0
+stepnum: 1
+ref: modify-psa-replica-set-add-or-modify
+pre: |
+  To avoid rolling back uncommitted writes when adding or changing a
+  voting, data-bearing node, it is required that you add the node with
+  ``{ priority: 0 }`` first.
+
+  In :mongosh:`mongosh </>`, modify the replica set configuration. To
+  reconfigure an existing replica set, first retrieve the current
+  configuration with :method:`rs.conf()`, modify the configuration
+  document as needed, and then pass the modified document to
+  :method:`rs.reconfig()`:
+action:
+  language: javascript
+  code: |
+     cfg = rs.conf();
+     cfg["members"] = [
+       {
+          // existing member or members
+       },
+       {
+          "_id" : <num>,  // The array position of the new member in the
+                          // ``members`` array.
+          "host" : <host>,
+          "arbiterOnly" : false,
+          "buildIndexes" : true,
+          "hidden" : false,
+          "priority" : 0,
+          "tags" : { <tags> },
+          "secondaryDelaySecs" : <num>,
+          "votes" : 1
+       },
+       {
+          // existing member or members
+       }
+     ]
+     rs.reconfig(cfg);
+---
+title: Reconfigure the secondary to have non-zero priority
+stepnum: 2
+ref: modify-psa-replica-set-reconfigure
+pre: |
+  Once the secondary is caught up, set the prority to the desired
+  number. Before this reconfiguration succeeds, the secondary must
+  replicate all the writes that were committed when it had zero votes.
+  This is automatically checked when you issue the
+  :method:`rs.reconfig()` command.
+
+action:
+  language: javascript
+  code: |
+     cfg = rs.conf();
+     cfg["members"] = [
+       {
+          // existing member or members
+       },
+       {
+          "_id" : <num>,  // The array position of the new member in the
+                          // ``members`` array.
+          "host" : <host>,
+          "arbiterOnly" : false,
+          "buildIndexes" : true,
+          "hidden" : false,
+          "priority" : <num>,
+          "tags" : { <tags> },
+          "secondaryDelaySecs" : <num>,
+          "votes" : 1
+       },
+       {
+          // existing member or members
+       }
+     ]
+     rs.reconfig(cfg);
+...

source/release-notes/5.0.txt

@@ -236,8 +236,9 @@ Reconfiguring PSA Replica Sets
 When reconfiguring primary-secondary-arbiter (PSA) replica sets or
 changing to a PSA architecture, it is now in some cases required to
 perform the reconfiguration in a two-step change. MongoDB 5.0 introduces
-the :method:`rs.reconfigForPSASet()` method which performs both steps
-together.
+the :method:`rs.reconfigForPSASet()` method which performs both steps.
+If you cannot use the helper method, follow the procedure in
+:ref:`modify-psa-replica-set-safely`.
 
 .. _5.0-rel-notes-security:
 

source/tutorial/modify-psa-replica-set-safely.txt

@@ -0,0 +1,61 @@
+.. _modify-psa-replica-set-safely:
+
+=============================
+Modify PSA Replica Set Safely
+=============================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+Overview
+--------
+
+When reconfiguring primary-secondary-arbiter (PSA) replica sets or
+changing to a PSA architecture, you need to take special care in 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 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
+  primary 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.
+
+This document outlines the procedure for reconfiguring your replica set
+in these specific cases **without** using the designated helper method
+:method:`rs.reconfigForPSASet`.
+
+Procedure
+---------
+
+If you are performing one of the preceding operations, it is necessary
+to reconfigure your replica set in two steps:
+
+1. Reconfigure the 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, reconfigure the secondary to have a non-zero
+   priority ``{ 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
+primary.
+
+To run the :method:`rs.reconfigForPSASet()` method, you must connect
+to the :term:`primary` of the replica set.
+
+.. include:: /includes/steps/modify-psa-replica-set-safely.rst