Change Hostnames in a Replica Set

Change Hostnames in a Replica Set

For most replica sets, the hostnames in themembers[n].host field never change.However, if organizational needs change, you might need to migrate someor all host names.

Note

Always use resolvable hostnames for the value of themembers[n].host field in the replicaset configuration to avoid confusion and complexity.

Tip

When possible, use a logical DNS hostname instead of an ip address,particularly when configuring replica set members or sharded clustermembers. The use of logical DNS hostnames avoids configurationchanges due to ip address changes.

Overview

This document provides two separate procedures for changing thehostnames in the members[n].hostfield. Use either of the following approaches:

Change hostnames without disrupting availability. This approach ensures yourapplications will always be able to read and write data to the replicaset, but the approach can take a long time and may incur downtime atthe application layer.

If you use the first procedure, you must configure your applicationsto connect to the replica set at both the old and new locations, whichoften requires a restart and reconfiguration at the application layerand which may affect the availability of your applications.Re-configuring applications is beyond the scope of this document.

Stop all members running on the old hostnames at once. This approach has a shortermaintenance window, but the replica set will be unavailable duringthe operation.

Assumptions

Given a replica set with three members:

database0.example.com:27017 (the primary)
database1.example.com:27017
database2.example.com:27017

And with the following rs.conf() output:

{
    "_id" : "rs",
    "version" : 3,
    "members" : [
        {
            "_id" : 0,
            "host" : "database0.example.com:27017"
        },
        {
            "_id" : 1,
            "host" : "database1.example.com:27017"
        },
        {
            "_id" : 2,
            "host" : "database2.example.com:27017"
        }
    ]
}

The following procedures change the members’ hostnames as follows:

mongodb0.example.net:27017 (the primary)
mongodb1.example.net:27017
mongodb2.example.net:27017

Use the most appropriate procedure for your deployment.

Change Hostnames while Maintaining Replica Set Availability

This procedure uses the above assumptions.

For each secondary in the replica set, perform thefollowing sequence of operations:
- Stop the secondary.
- Restart the secondary at the new location.
- Open a mongo shell connected to the replica set’sprimary. In our example, the primary runs on port 27017 so youwould issue the following command:

mongo --port 27017

Use rs.reconfig() to update the replica setconfiguration document withthe new hostname.

For example, the following sequence of commands updates thehostname for the secondary at the array index 1 of themembers array (i.e. members[1]) in the replica setconfiguration document:

cfg = rs.conf()
cfg.members[1].host = "mongodb1.example.net:27017"
rs.reconfig(cfg)

For more information on updating the configuration document, seeExamples.

Make sure your client applications are able to access theset at the new location and that the secondary has a chance tocatch up with the other members of the set.

Repeat the above steps for each non-primary member of the set.

Open a mongo shell connected to the primary and stepdown the primary using the rs.stepDown() method:

rs.stepDown()

The replica set elects another member to the become primary.

When the step down succeeds, shut down the old primary.
Start the mongod instance that will become the new primaryin the new location.
Connect to the current primary, which was just elected, and updatethe replica set configuration document with the hostname of the node thatis to become the new primary.

For example, if the old primary was at position 0 and the newprimary’s hostname is mongodb0.example.net:27017, you would run:

cfg = rs.conf()
cfg.members[0].host = "mongodb0.example.net:27017"
rs.reconfig(cfg)

Open a mongo shell connected to the new primary.
To confirm the new configuration, call rs.conf() in themongo shell.

Your output should resemble:

{
    "_id" : "rs",
    "version" : 4,
    "members" : [
        {
            "_id" : 0,
            "host" : "mongodb0.example.net:27017"
        },
        {
            "_id" : 1,
            "host" : "mongodb1.example.net:27017"
        },
        {
            "_id" : 2,
            "host" : "mongodb2.example.net:27017"
        }
    ]
}

Change All Hostnames at the Same Time

This procedure uses the above assumptions.

Prerequisites

The following procedure reads and updates the system.replsetcollection in the local database.

If your deployment enforces access control, the user performing the procedure must havefind and update privilege actions on thesystem.replset collection.

To create a role that provides the necessary privileges:

Log in as a user with privileges to manage users and roles, such asa user with userAdminAnyDatabase role. The followingprocedure uses the myUserAdmin created inEnable Access Control.

mongo --port 27017 -u myUserAdmin --authenticationDatabase 'admin' -p

Create a user role that provides the necessary privileges on thesystem.replset collection in the local database:

db.adminCommand( {
   createRole: "systemreplsetRole",
   privileges: [
      { resource: { db: "local", collection: "system.replset" }, actions: ["find","update"] }
   ],
   roles: []
} );

Grant the role to the user who will be performing the renameprocedure. For example, the following assumes an existing user"userPerformingRename" in the admin database.

use admin
db.grantRolesToUser( "userPerformingRename", [ { role: "systemreplsetRole", db: "admin" } ] );

Procedure

Stop all members in the replica set.
Restart each member on a different port and without using the—replSet run-time option. Changingthe port number during maintenance prevents clients from connectingto this host while you perform maintenance. Use the member’s usual—dbpath, which in thisexample is /data/db1. Use a command that resembles the following:

Warning

Before binding to a non-localhost (e.g. publicly accessible)IP address, ensure you have secured your cluster from unauthorizedaccess. For a complete list of security recommendations, seeSecurity Checklist. At minimum, considerenabling authentication andhardening network infrastructure.

mongod --dbpath /data/db1/ --port 37017 --bind_ip localhost,<hostname(s)|ip address(es)>

Tip

For each member of the replica set, perform the following sequenceof operations:
- Open a mongo shell connected to the mongodrunning on the new, temporary port. For example, for a memberrunning on a temporary port of 37017, you would issue thiscommand:

mongo --port 37017

If running with access control, connect as a user withappropriate privileges. SeePrerequisites.

mongo --port 37017 -u userPerformingRename --authenticationDatabase=admin  -p

Edit the replica set configuration manually. The replica setconfiguration is the only document in the system.replsetcollection in the local database. Edit the replica setconfiguration with the new hostnames and correct ports for allthe members of the replica set. Consider the following sequence ofcommands to change the hostnames in a three-member set:

use local
 
cfg = db.system.replset.findOne( { "_id": "rs" } )
 
cfg.members[0].host = "mongodb0.example.net:27017"
 
cfg.members[1].host = "mongodb1.example.net:27017"
 
cfg.members[2].host = "mongodb2.example.net:27017"
 
db.system.replset.update( { "_id": "rs" } , cfg )

Stop the mongod process on the member.

After re-configuring all members of the set, start eachmongod instance in the normal way: use the usual portnumber and use the —replSet option. Forexample:

Warning

mongod --dbpath /data/db1/ --port 27017 --replSet rs --bind_ip localhost,<hostname(s)|ip address(es)>

Connect to one of the mongod instancesusing the mongo shell. For example:

mongo --port 27017

To confirm the new configuration, call rs.conf() in themongo shell.

Your output should resemble:

{
    "_id" : "rs",
    "version" : 4,
    "members" : [
        {
            "_id" : 0,
            "host" : "mongodb0.example.net:27017"
        },
        {
            "_id" : 1,
            "host" : "mongodb1.example.net:27017"
        },
        {
            "_id" : 2,
            "host" : "mongodb2.example.net:27017"
        }
    ]
}