DOCS-13922 describes procedure for renaming replica sets

Author: jmd-mongo

source/administration/replica-set-maintenance.txt

@@ -51,6 +51,9 @@ 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.
+
 
 .. toctree::
    :titlesonly: 
@@ -65,3 +68,4 @@ replica sets.
    /tutorial/manage-chained-replication
    /tutorial/change-hostnames-in-a-replica-set
    /tutorial/configure-replica-set-secondary-sync-target
+   /tutorial/rename-unsharded-replica-set

source/faq/replica-sets.txt

@@ -112,9 +112,11 @@ times.
 Can I rename a replica set?
 ---------------------------
 
-No.
+Yes, unsharded replica sets can be renamed. This procedure requires
+downtime.
 
-You can use the backup and restore procedure described in the
-:doc:`/tutorial/restore-replica-set-from-backup` tutorial to create a
-new replica set with the desired name. Downtime may be necessary in
-order to ensure parity between the original replica set and the new one.
+To learn how to rename your replica set, see
+:doc:`/tutorial/rename-unsharded-replica-set`.
+
+Before renaming a replica set, perform a full
+:doc:`backup of your MongoDB deployment </core/backups>`.

source/includes/steps-rename-unsharded-replica-set.yaml

@@ -0,0 +1,64 @@
+title: Shut down replica set members.
+level: 4
+ref: shutdown-replica-set
+content: |
+  Follow the procedure in :ref:`Stop a Replica Set <stop-replica-set>`
+  to confirm that replica set members are 
+  :ref:`shut down <terminate-mongod-processes>`.
+
+  .. warning::
+     
+     This step requires downtime as all replica members will need to be 
+     shut down.
+
+---
+title: Rename the replica set.
+level: 4
+ref: rename-the-replica-set
+content: |
+  Perform the following steps for each replica set member:
+  
+  a. Update the replica set name. 
+
+     - If using a :ref:`configuration file <conf-file>`, set 
+       :setting:`replication.replSetName <replication.replSetName>` 
+       to the new name. 
+
+     - If using the :binary:`~bin.mongod` startup command with 
+       the :option:`--replSet <mongod --replSet>` option, note down the 
+       new replica set name for use in step f.
+  
+  #. Start the replica set member on a different port without the
+     :option:`--replSet <mongod --replSet>` option. 
+  
+  #. Connect to the replica set member. 
+ 
+  #. Update the replica set name in the :ref:`local database 
+     <replica-set-local-database>` with the following commands:
+
+     .. code-block:: javascript
+
+        /* Set `newId` to the new replica set name */
+        var newId = '<new replica set name>'
+
+        var doc = db.getSiblingDB("local").system.replset.findOne()
+        var oldId = doc._id
+        doc._id = newId
+        db.getSiblingDB("local").system.replset.save(doc)
+        db.getSiblingDB("local").system.replset.remove({_id: oldId})
+
+  #. :ref:`Shut down <terminate-mongod-processes>` the replica set 
+     member.
+ 
+  #. Start the replica set member on its original port. 
+  
+     - If using a configuration file, ensure that 
+       :setting:`replication.replSetName <replication.replSetName>` is 
+       set to the new replica set name.
+     
+     - If using the :binary:`~bin.mongod` startup command with 
+       the :option:`--replSet <mongod --replSet>` option, pass the new 
+       name of the replica set to the 
+       :option:`--replSet <mongod --replSet>` option.
+       
+...

source/reference/replica-configuration.txt

@@ -38,8 +38,7 @@ Replica Set Configuration Fields
 
    *Type*: string
 
-   The name of the replica set. Once set, you cannot change the
-   name of a replica set.
+   The name of the replica set.
 
    :rsconf:`_id` *must* be identical to the
    :setting:`replication.replSetName` or the value of `--replSet`

source/tutorial.txt

@@ -61,6 +61,7 @@ Replica Sets
 - :doc:`/tutorial/reconfigure-replica-set-with-unavailable-members`
 - :doc:`/tutorial/recover-data-following-unexpected-shutdown`
 - :doc:`/tutorial/troubleshoot-replica-sets`
+- :doc:`/tutorial/rename-unsharded-replica-set`
 
 Sharding
 ~~~~~~~~

source/tutorial/manage-mongodb-processes.txt

@@ -197,6 +197,8 @@ Starting in MongoDB 4.0.8 (and 3.6.15), if a replica set primary receives a
 
    Never use ``kill -9`` (i.e. ``SIGKILL``) to terminate a mongod instance.
 
+.. _stop-replica-set:
+
 Stop a Replica Set
 ------------------
 

source/tutorial/rename-unsharded-replica-set.txt

@@ -0,0 +1,31 @@
+====================
+Rename a Replica Set
+====================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+To rename a replica set, you must shut down all members of the replica 
+set, then configure each member's ``local`` database with the new 
+replica set name.
+
+This procedure requires downtime.
+
+Prerequisites
+-------------
+
+- Ensure your replica set is not sharded. The renaming procedure 
+  is for unsharded replica sets only. 
+
+- Before renaming a replica set, perform a full
+  :doc:`backup of your MongoDB deployment </core/backups>`.
+
+Procedure
+---------
+
+.. include:: /includes/steps/rename-unsharded-replica-set.rst