From 12b8cf35b46013ca2f05c02bb959113a6c55214d Mon Sep 17 00:00:00 2001 From: Joseph Dougherty Date: Thu, 25 Feb 2021 15:57:49 -0500 Subject: [PATCH] DOCS-13922 describes procedure for renaming replica sets --- .../replica-set-maintenance.txt | 4 ++ source/faq/replica-sets.txt | 12 ++-- .../steps-rename-unsharded-replica-set.yaml | 64 +++++++++++++++++++ source/reference/replica-configuration.txt | 3 +- source/tutorial.txt | 1 + source/tutorial/manage-mongodb-processes.txt | 2 + .../tutorial/rename-unsharded-replica-set.txt | 31 +++++++++ 7 files changed, 110 insertions(+), 7 deletions(-) create mode 100644 source/includes/steps-rename-unsharded-replica-set.yaml create mode 100644 source/tutorial/rename-unsharded-replica-set.txt diff --git a/source/administration/replica-set-maintenance.txt b/source/administration/replica-set-maintenance.txt index 5d05f56dce0..3ce1a0bc812 100644 --- a/source/administration/replica-set-maintenance.txt +++ b/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 diff --git a/source/faq/replica-sets.txt b/source/faq/replica-sets.txt index 87a111156e0..b3f2689dd46 100644 --- a/source/faq/replica-sets.txt +++ b/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 `. diff --git a/source/includes/steps-rename-unsharded-replica-set.yaml b/source/includes/steps-rename-unsharded-replica-set.yaml new file mode 100644 index 00000000000..aa747a968a5 --- /dev/null +++ b/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 ` + to confirm that replica set members are + :ref:`shut down `. + + .. 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 `, set + :setting:`replication.replSetName ` + to the new name. + + - If using the :binary:`~bin.mongod` startup command with + the :option:`--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 ` option. + + #. Connect to the replica set member. + + #. Update the replica set name in the :ref:`local database + ` with the following commands: + + .. code-block:: javascript + + /* Set `newId` to the new replica set name */ + var newId = '' + + 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 ` the replica set + member. + + #. Start the replica set member on its original port. + + - If using a configuration file, ensure that + :setting:`replication.replSetName ` is + set to the new replica set name. + + - If using the :binary:`~bin.mongod` startup command with + the :option:`--replSet ` option, pass the new + name of the replica set to the + :option:`--replSet ` option. + +... diff --git a/source/reference/replica-configuration.txt b/source/reference/replica-configuration.txt index e3a69ebf586..7b10280f4a5 100644 --- a/source/reference/replica-configuration.txt +++ b/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` diff --git a/source/tutorial.txt b/source/tutorial.txt index 228e8603257..1e95c25530b 100644 --- a/source/tutorial.txt +++ b/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 ~~~~~~~~ diff --git a/source/tutorial/manage-mongodb-processes.txt b/source/tutorial/manage-mongodb-processes.txt index 09eaf1053d4..3e7352af485 100644 --- a/source/tutorial/manage-mongodb-processes.txt +++ b/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 ------------------ diff --git a/source/tutorial/rename-unsharded-replica-set.txt b/source/tutorial/rename-unsharded-replica-set.txt new file mode 100644 index 00000000000..bf3ddcb18c6 --- /dev/null +++ b/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 `. + +Procedure +--------- + +.. include:: /includes/steps/rename-unsharded-replica-set.rst