Change Hostnames in a Replica Set¶

On this page

Overview
Assumptions
Change Hostnames while Maintaining Replica Set Availability
Change All Hostnames at the Same Time

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

Note

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

Overview¶

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

Change hostnames without disrupting availability. This approach ensures your applications will always be able to read and write data to the replica set, but the approach can take a long time and may incur downtime at the application layer.

If you use the first procedure, you must configure your applications to connect to the replica set at both the old and new locations, which often requires a restart and reconfiguration at the application layer and 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 shorter maintenance window, but the replica set will be unavailable during the 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 the following sequence of operations:
1. Stop the secondary.
2. Restart the secondary at the new location.
3. Open a mongo shell connected to the replica set’s primary. In our example, the primary runs on port 27017 so you would issue the following command:
```
mongo --port 27017
```
4. Use rs.reconfig() to update the replica set configuration document with the new hostname.
  
  For example, the following sequence of commands updates the hostname for the secondary at the array index 1 of the members array (i.e. members[1]) in the replica set configuration document:
```
cfg = rs.conf()
cfg.members[1].host = "mongodb1.example.net:27017"
rs.reconfig(cfg)
```
  For more information on updating the configuration document, see Examples.
5. Make sure your client applications are able to access the set at the new location and that the secondary has a chance to catch 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 step down 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 primary in the new location.
Connect to the current primary, which was just elected, and update the replica set configuration document with the hostname of the node that is to become the new primary.

For example, if the old primary was at position 0 and the new primary’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 the mongo 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.

Stop all members in the replica set.
Restart each member on a different port and without using the --replSet run-time option. Changing the port number during maintenance prevents clients from connecting to this host while you perform maintenance. Use the member’s usual --dbpath, which in this example is /data/db1. Use a command that resembles the following:
```
mongod --dbpath /data/db1/ --port 37017
```
For each member of the replica set, perform the following sequence of operations:
1. Open a mongo shell connected to the mongod running on the new, temporary port. For example, for a member running on a temporary port of 37017, you would issue this command:
```
mongo --port 37017
```
2. Edit the replica set configuration manually. The replica set configuration is the only document in the system.replset collection in the local database. Edit the replica set configuration with the new hostnames and correct ports for all the members of the replica set. Consider the following sequence of commands 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 )
```
3. Stop the mongod process on the member.
After re-configuring all members of the set, start each mongod instance in the normal way: use the usual port number and use the --replSet option. For example:
```
mongod --dbpath /data/db1/ --port 27017 --replSet rs
```
Connect to one of the mongod instances using the mongo shell. For example:
```
mongo --port 27017
```

To confirm the new configuration, call rs.conf() in the mongo 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"
        }
    ]
}

← Manage Chained Replication Configure a Secondary’s Sync Target →