DOCS-15066 refactor Convert Replica Set to Replicated Shard Cluster (#479) (#581)

* refactor Convert Replica Set to Replicated Shard Cluster

* review feedback

* removes Downtime sub-heading

* review feedback

* fixes typo

* updates warning

* let users know they may need to restart apps connected to secondaries

* updates primary warning

* clarifies primary warning and moves to the primary stepdown section

Author: jmd-mongo

source/includes/fact-3.4-shardsvr-required.rst renamed to source/includes/fact-shardsvr-required.rst

@@ -1,4 +1,4 @@
-For MongoDB 3.4 sharded clusters, :binary:`~bin.mongod` instances for
+For sharded clusters, :binary:`~bin.mongod` instances for
 the shards **must** explicitly specify its role as a ``shardsvr``,
 either via the configuration file setting
 :setting:`sharding.clusterRole` or via the command line option

source/includes/steps-convert-replica-set-shard-aware.yaml

@@ -9,9 +9,21 @@ title: Restart secondary members with the ``--shardsvr`` option.
 level: 4
 ref: restart-secondary
 pre: |
-  One secondary at a time, restart each :ref:`secondary
-  <replica-set-secondary-members>` with the :option:`--shardsvr <mongod --shardsvr>`
-  option. To continue to use the same port, include the :option:`--port <mongod --port>`
+  One secondary at a time, :ref:`shut down <terminate-mongod-processes>` 
+  and restart each :ref:`secondary <replica-set-secondary-members>` 
+  with the :option:`--shardsvr <mongod --shardsvr>` option. 
+  
+  .. warning::
+
+     This step requires some downtime for applications connected to 
+     secondary members of the replica set. Applications connected to a 
+     secondary may error with ``CannotVerifyAndSignLogicalTime`` after 
+     restarting the secondary until you perform the steps in 
+     :ref:`convert-add-initial-shard`. Restarting your application will
+     also stop it from receiving ``CannotVerifyAndSignLogicalTime`` 
+     errors.
+
+  To continue to use the same port, include the :option:`--port <mongod --port>`
   option. Include additional options, such as :option:`--bind_ip <mongod --bind_ip>`, as
   appropriate for your deployment.
 
@@ -30,6 +42,14 @@ level: 4
 ref: step-down-primary
 pre: |
   Connect :binary:`~bin.mongosh` to the primary and stepdown the primary.
+
+  .. warning::
+
+     This step requires some downtime. Applications may error with 
+     ``CannotVerifyAndSignLogicalTime`` after stepping down the primary 
+     until you perform the steps in :ref:`convert-add-initial-shard`.
+     Restarting your application will also stop it from receiving 
+     ``CannotVerifyAndSignLogicalTime`` errors. 
 action:
   language: javascript
   code: |
@@ -39,7 +59,8 @@ title: Restart the primary with the ``--shardsvr`` option.
 level: 4
 ref: restart-primary
 pre: |
-  Restart the primary with the :option:`--shardsvr <mongod --shardsvr>` option.
+  :ref:`Shut down <terminate-mongod-processes>` the primary and restart with the :option:`--shardsvr <mongod --shardsvr>` option.
+
   To continue to use the same port, include the :option:`--port <mongod --port>`  option.
 action:
     language: javascript

source/tutorial/convert-replica-set-to-replicated-shard-cluster.txt

@@ -35,6 +35,18 @@ The procedure is as follows:
 
 #. Shard the desired collection. See :ref:`convert-shard-collection`.
 
+
+Considerations
+--------------
+
+
+Individual steps in these procedures note when downtime will occur.
+
+.. important::
+
+   These procedures cause some downtime for your deployment.
+
+
 Prerequisites
 -------------
 
@@ -69,15 +81,6 @@ The replica set members are on the following hosts:
 For more information on deploying a replica set, see
 :doc:`/tutorial/deploy-replica-set`.
 
-Restart the Replica Set as a Shard
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. versionchanged:: 3.4
-
-  .. include:: /includes/fact-3.4-shardsvr-required.rst
-
-.. include:: /includes/steps/convert-replica-set-shard-aware.rst
-
 .. _convert-deploy-sharding-infrastructure:
 
 Deploy Config Server Replica Set and ``mongos``
@@ -92,8 +95,16 @@ servers </core/sharded-cluster-config-servers>` and the
 
 - The :binary:`~bin.mongos` uses ``mongodb6.example.net``.
 
+
 .. include:: /includes/steps/convert-replica-set-shard-deploy-infrastructure.rst
 
+Restart the Replica Set as a Shard
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: /includes/fact-shardsvr-required.rst
+
+.. include:: /includes/steps/convert-replica-set-shard-aware.rst
+
 .. _convert-add-initial-shard:
 
 Add Initial Replica Set as a Shard
@@ -113,9 +124,7 @@ second shard and adds it to the cluster. The replica set members are on
 the following hosts: ``mongodb3.example.net``,
 ``mongodb4.example.net``, and ``mongodb5.example.net``.
 
-.. versionchanged:: 3.4
-
-  .. include:: /includes/fact-3.4-shardsvr-required.rst
+.. include:: /includes/fact-shardsvr-required.rst
 
 .. include:: /includes/steps/convert-replica-set-add-new-shard.rst