Add Members to a Replica Set

Overview

This tutorial explains how to add an additional member to an existingreplica set. For background on replication deployment patterns,see the Replica Set Deployment Architectures document.

Maximum Voting Members

A replica set can have a maximum of seven voting members. To add a member to a replica setthat already has seven voting members, you must either add the member as anon-voting member or remove avote from an existing member.

Init Scripts

In production deployments you can configure a init scriptto manage member processes.

Existing Members

You can use these procedures to add new members to an existingset. You can also use the same procedure to “re-add” a removedmember. If the removed member’s data is still relatively recent, itcan recover and catch up easily.

Data Files

If you have a backup or snapshot of an existing member, you can movethe data files (e.g. the dbPath directory) to a new systemand use them to quickly initiate a new member. The files must be:

• A valid copy of the data files from a member of the same replicaset. See Back Up and Restore with Filesystem Snapshotsdocument for more information.

Important

Always use filesystem snapshots to create a copy of amember of the existing replica set. Do not usemongodump and mongorestore to seed a newreplica set member.

• More recent than the oldest operation in the primary’soplog. The new member must be able to becomecurrent by applying operations from the primary’s oplog.

IP Binding

Starting in MongoDB 3.6, MongoDB binaries, mongod andmongos, bind to localhost by default. If thenet.ipv6 configuration file setting or the —ipv6command line option is set for the binary, the binary additionally bindsto the localhost IPv6 address.

Previously, starting from MongoDB 2.6, only the binaries from theofficial MongoDB RPM (Red Hat, CentOS, Fedora Linux, and derivatives)and DEB (Debian, Ubuntu, and derivatives) packages bind to localhost bydefault.

When bound only to the localhost, these MongoDB 3.6 binaries can onlyaccept connections from clients (including the mongo shell,other members in your deployment for replica sets and sharded clusters)that are running on the same machine. Remote clients cannot connect tothe binaries bound only to localhost.

To override and bind to other ip addresses, you can use thenet.bindIp configuration file setting or the—bind_ip command-line option to specify a list of hostnames or ipaddresses.

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.

For example, the following mongod instance binds to boththe localhost and the hostname My-Example-Associated-Hostname, which isassociated with the ip address 198.51.100.1:

mongod --bind_ip localhost,My-Example-Associated-Hostname

In order to connect to this instance, remote clients must specifythe hostname or its associated ip address 198.51.100.1:

mongo --host My-Example-Associated-Hostname
 
mongo --host 198.51.100.1

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.

Requirements

• An active replica set.
• A new MongoDB system capable of supporting your data set, accessible bythe active replica set through the network.Otherwise, use the MongoDB installation tutorial and the Deploy a Replica Settutorials.

Procedures

Prepare the Data Directory

Before adding a new member to an existing replica set, preparethe new member’s data directory using one of thefollowing strategies:

• Make sure the new member’s data directory does not contain data. Thenew member will copy the data from an existing member.

If the new member is in a recovering state, it must exit andbecome a secondary before MongoDBcan copy all data as part of the replication process. This processtakes time but does not require administrator intervention.

• Manually copy the data directory from an existing member. The newmember becomes a secondary member and will catch up to the currentstate of the replica set. Copying the data over may shorten theamount of time for the new member to become current.

Ensure that you can copy the data directory to the new member andbegin replication within the window allowed by the oplog. Otherwise, the new instance will haveto perform an initial sync, which completely resynchronizes thedata, as described in Resync a Member of a Replica Set.

Use rs.printReplicationInfo() to check the current stateof replica set members with regards to the oplog.

For background on replication deployment patterns, see theReplica Set Deployment Architectures document.

Add a Member to an Existing Replica Set

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.

• Start the new mongod instance. Specify the data directoryand the replica set name. The following example specifies the/srv/mongodb/db0 data directory and the rs0 replica set:

mongod --dbpath /srv/mongodb/db0 --replSet rs0  --bind_ip localhost,<hostname(s)|ip address(es)>

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.

For more information on configuration options, see themongod manual page.

Optional

You can specify the data directory, replica set name, and the ipbinding in the mongod.conf configuration file, and start themongod with the following command:

mongod --config /etc/mongod.conf

• Connect to the replica set’s primary.

You can only add members while connected to the primary. If you donot know which member is the primary, log into any member of thereplica set and issue the db.isMaster() command.

• Use rs.add() to add the new member to the replica set.Pass the member configuration document to themethod. For example, to add a member at hostmongodb3.example.net, issue the following command:

rs.add( { host: "mongodb3.example.net:27017", priority: 0, votes: 0 } )

Tip

When a newly added secondary has its votes andpriority settings greater than zero, duringits initial sync, the secondary still counts as a voting member eventhough it cannot serve reads nor become primary because its data isnot yet consistent.

This can lead to a case where a majority of the voting members areonline but no primary can be elected. To avoid such situations,consider adding the new secondary initially withpriority :0 and votes :0. Then, once the member has transitioned intoSECONDARY state, use rs.reconfig() to update itspriority and votes.

• Ensure that the new member has reached SECONDARY state.To check the state of the replica set members, runrs.status():

rs.status()

• Once the newly added member has transitioned intoSECONDARY state, use rs.reconfig() to updatethe newly added member’s priority andvotes if needed.

For example, if rs.conf() returns the configurationdocument for mongodb3.example.net:27017 as the fifth element inthe members array, to update its priority and votes to1, use the following sequence of operations:

var cfg = rs.conf();
cfg.members[4].priority = 1
cfg.members[4].votes = 1
rs.reconfig(cfg)

Warning

• The rs.reconfig() shell method can force the currentprimary to step down, which causes an election. When the primary steps down, themongod closes all client connections. While thistypically takes 10-20 seconds, try to make these changes duringscheduled maintenance periods.
• Avoid reconfiguring replica sets that contain members of differentMongoDB versions as validation rules may differ across MongoDB versions.