- Replication >
- Change Hostnames in a Replica Set
Change Hostnames in a Replica Set¶
On this page
Overview¶
For most replica sets the hostnames
[1] in the
host
field never
change. However, in some cases you must migrate some or all host names
in a replica set as organizational needs change. This document
presents two possible procedures for changing the hostnames in the
host
field. Depending on your
environments availability requirements, you may:
Make the configuration change without disrupting the availability of the replica set. While this ensures that your application will always be able to read and write data to the replica set, this procedure can take a long time and may incur downtime at the application layer. [2]
For this procedure, see Changing Hostnames while Maintaining the Replica Set’s Availability.
Stop all members of the replica set at once running on the “old” hostnames or interfaces, make the configuration changes, and then start the members at the new hostnames or interfaces. While the set will be totally unavailable during the operation, the total maintenance window is often shorter.
For this procedure, see Changing All Hostnames in Replica Set at Once.
See also
And the following tutorials:
[1] | Always use resolvable hostnames
for the value of the host field in the replica
set configuration to avoid confusion and complexity. |
[2] | You will have to configure your applications so that they can connect to the replica set at both the old and new locations. This often requires a restart and reconfiguration at the application layer, which may affect the availability of your applications. This re-configuration is beyond the scope of this document and makes the second option preferable when you must change the hostnames of all members of the replica set at once. |
Procedures¶
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:
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.
Changing Hostnames while Maintaining the Replica Set’s Availability¶
This procedure uses the above assumptions.
For each secondary in the replica set, perform the following sequence of operations:
Stop the secondary.
Restart the secondary at the new location.
Open a
mongo
shell connected to the replica set’s primary. In our example, the primary runs on port27017
so you would issue the following command:Run the following reconfigure option, for the
host
value wheren
is1
:See Replica Set Configuration for more information.
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 usingreplSetStepDown
. In themongo
shell, use thers.stepDown()
wrapper, as follows:When the step down succeeds, shut down the primary.
To make the final configuration change, connect to the new primary in the
mongo
shell and reconfigure thehost
value wheren
is0
:Start the original primary.
Open a
mongo
shell connected to the primary.To confirm the new configuration, call
rs.conf()
in themongo
shell.Your output should resemble:
Changing All Hostnames in Replica Set at Once¶
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:For each member of the replica set, perform the following sequence of operations:
Open a
mongo
shell connected to themongod
running on the new, temporary port. For example, for a member running on a temporary port of37017
, you would issue this command:Edit the replica set configuration manually. The replica set configuration is the only document in the
system.replset
collection in thelocal
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: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:Connect to one of the
mongod
instances using themongo
shell. For example:To confirm the new configuration, call
rs.conf()
in themongo
shell.Your output should resemble: