Add a Member to a Shard
On this page
You can add members to an existing shard in a sharded cluster. You might want to add a member to a shard for the same reasons you'd want to add a member to any replica set. For example, increasing the number of members provides additional candidates to replace a primary in the event of a failover. Additional members also increase data redundancy and replica set availability.
For more information, refer to Replica Set Deployment Architectures.
About This Task
Before MongoDB 5.0, a newly added secondary still counts as a voting
member even though it can neither serve reads nor become primary until
its data is consistent. If you are running a MongoDB version earlier
than 5.0 and add a secondary with its votes
and priority
settings greater than zero, this can
lead to a case where a majority of the voting members are
online but no primary can be elected. To avoid such situations,
consider adding the new secondary initially with
priority :0
and votes :0
. Then, run rs.status()
to ensure the
member has transitioned into SECONDARY
state. Finally, use
rs.reconfig()
to update its priority and votes.
Before You Begin
To add a member to a shard replica set, you need:
An active sharded cluster replica set.
A new host server for the new member. The new host server must be able to support your sharded data set and be accessible by the active replica set through the network.
Starting in MongoDB 8.0, you can use the
directShardOperations
role to perform maintenance operations
that require you to execute commands directly against a shard.
Warning
Running commands using the directShardOperations
role can cause
your cluster to stop working correctly and may cause data corruption.
Only use the directShardOperations
role for maintenance purposes
or under the guidance of MongoDB support. Once you are done
performing maintenance operations, stop using the
directShardOperations
role.
Steps
Prepare the Data Directory
Prepare the new member's data directory using one of the following strategies:
Have the new member automatically sync data from an existing member. This process takes time but does not require administrator intervention.
Make sure the new member's data directory does not contain data. The new member will copy the data from an existing member.
If the new member is in a recovering state, it must exit and become a secondary before MongoDB can copy all data as part of the replication process.
Manually copy the data directory from an existing member. The new member becomes a secondary member and will catch up to the current state of the replica set. Copying the data over may shorten the amount of time it takes for the new member to sync with the other replica set members.
Ensure that you can copy the data directory to the new member and begin replication within the window allowed by the oplog. Otherwise, the new instance will have to perform an initial sync, which completely resynchronizes the data, as described in Resync a Member of a Self-Managed Replica Set.
To check the current state of replica set members with regards to the oplog, use
rs.printReplicationInfo()
.
For background on replication deployment patterns, see the Replica Set Deployment Architectures document.
Start the new mongod
instance
Specify the data directory
and 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,<ip address of the mongod host>
Warning
Before you bind your instance to a publicly-accessible IP address, you must secure your cluster from unauthorized access. For a complete list of security recommendations, see Security Checklist for Self-Managed Deployments. At minimum, consider enabling authentication and hardening network infrastructure.
For more information on configuration options, see the
mongod
manual page.
Tip
You can specify the data directory, replica set name, and the ip
binding in the mongod.conf
configuration file, and start the
mongod
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. To connect to
the primary, use mongosh
. Replace the host
and port
values
with relevant values for your deployment:
mongosh --host mongodb0.example.com --port 28015
If you do not know which member is the primary, connect to any member
of the replica set and issue the db.hello()
command.
Use rs.add()
to add the new member to the replica set
Pass the member configuration document
to the
method. For example, to add a member at host
mongodb3.example.net
, issue the following command:
rs.add( { host: "mongodb3.example.net:27017", priority: 0, votes: 0 } )
Ensure that the new member has reached SECONDARY
state
To check the state of the replica set members, run
rs.status()
:
rs.status()
Next Steps
Once the newly added member has transitioned into
SECONDARY
state, use rs.reconfig()
to update
the newly added member's priority
and
votes
if needed.
Warning
The
rs.reconfig()
shell method can force the current primary to step down, which causes an election. When the primary steps down, themongod
closes all client connections. While this typically takes 10-20 seconds, try to make these changes during scheduled maintenance periods.Avoid reconfiguring replica sets that contain members of different MongoDB versions as validation rules may differ across MongoDB versions.
Example
If rs.conf()
returns the configuration document for
mongodb3.example.net:27017
as the fifth element in the
members
array, to update its priority and votes to
1
, use the following sequence of operations:
var cfg = rs.conf(); cfg.members[4].priority = 1 cfg.members[4].votes = 1 rs.reconfig(cfg)