Convert a Replica Set to a Sharded Cluster
On this page
- About This Task
- Server Architecture
- Before You Begin
- Steps
- 1. Deploy the Config Server Replica Set
- 2. Deploy the
mongos
- 3. Create an Administrative User for the Sharded Cluster
- 4. Migrate the
admin
Database from the Initial Replica Set - 5. Restart the Initial Replica Set as a Shard
- 6. Add the Initial Replica Set as a Shard
- 7. Update Your Application Connection String
- 8. Deploy a Second Replica Set
- 9. Add the Second Replica Set to the Cluster as a Shard
- 10. Shard a Collection
- Learn More
Sharded clusters partition data across multiple servers based on a shard key. A sharded cluster scales better than a replica set for deployments with large data sets and high throughput operations.
This tutorial converts a single three-member replica set to a sharded cluster with two shards. Each shard in the new cluster is an independent three-member replica set.
About This Task
Some steps in this tutorial cause downtime for your deployment. Individual steps note when downtime will occur.
This tutorial is for deployments that have authentication enabled.
In this tutorial, you specify server settings with configuration files. Configuration files contain settings that are equivalent to the
mongod
andmongos
command-line options.The sharded cluster you deploy with this tutorial contains ten servers:
One server for the
mongos
.Three servers each for the two shards in the cluster (six servers in total).
Three servers for the config server replica set.
Server Architecture
This tutorial uses the following servers:
Hostname | Port | Description |
---|---|---|
mongodb0.example.net | 27017 | Member of the initial data-bearing shard, rs0 . |
mongodb1.example.net | 27017 | Member of the initial data-bearing shard, rs0 . |
mongodb2.example.net | 27017 | Member of the initial data-bearing shard, rs0 . |
mongodb3.example.net | 27018 | Member of the second data-bearing shard, rs1 . |
mongodb4.example.net | 27018 | Member of the second data-bearing shard, rs1 . |
mongodb5.example.net | 27018 | Member of the second data-bearing shard, rs1 . |
mongodb6.example.net | 27017 | The mongos , used to connect to the sharded cluster. |
mongodb7.example.net | 27019 | Member of the config server replica set. |
mongodb8.example.net | 27019 | Member of the config server replica set. |
mongodb9.example.net | 27019 | Member of the config server replica set. |
The hostnames used in this tutorial are examples. Replace the hostnames used in the example commands with the hostnames used in your deployments.
Important
To avoid configuration updates due to IP address changes, use DNS hostnames instead of IP addresses. It is particularly important to use a DNS hostname instead of an IP address when configuring replica set members or sharded cluster members.
Use hostnames instead of IP addresses to configure clusters across a split network horizon. Starting in MongoDB 5.0, nodes that are only configured with an IP address will fail startup validation and will not start.
Before You Begin
To complete this tutorial, you must have a replica set that uses either keyfile or x.509 certificate authentication. To deploy a secure replica set that uses one of these authentication methods, see either:
This tutorial uses the default data directories
/data/db
and/data/configdb
. To use different paths, set thestorage.dbPath
setting in your configuration file.
Steps
To convert a replica set to a sharded cluster:
Deploy the config server replica set.
Deploy a
mongos
.Create an administrative user for the sharded cluster.
Migrate the
admin
database from the initial replica set to the sharded cluster.Restart the members of the initial replica set as shard servers.
Add the initial replica set as a shard.
Update your application connection string.
Create a second shard and add it to the cluster.
Shard a collection.
1. Deploy the Config Server Replica Set
Deploy a three-member replica set for the config servers. In this example, the config servers use the following hosts:
mongodb7.example.net
mongodb8.example.net
mongodb9.example.net
Deploy the config server replica set members.
Select the tab for your authentication mechanism:
Deploy the mongod
with your specified configuration:
mongod --config <PATH_TO_CONFIG_FILE>
The config servers use the default data directory
/data/configdb
and the default port 27019
.
Initiate the config server replica set.
To initiate the replica set, run rs.initiate()
:
rs.initiate( { _id: "configReplSet", configsvr: true, members: [ { _id: 0, host: "mongodb7.example.net:27019" }, { _id: 1, host: "mongodb8.example.net:27019" }, { _id: 2, host: "mongodb9.example.net:27019" } ] } )
The preceding command uses the localhost exception to perform administrative actions without authentication.
Important
Run rs.initiate()
on just one and only one
mongod
instance for the replica set.
2. Deploy the mongos

The mongos
provides the interface between the client
applications and the sharded cluster.
Deploy the mongos.
Deploy the mongos
with your specified configuration:
mongos --config <PATH_TO_CONFIG_FILE>
3. Create an Administrative User for the Sharded Cluster
After you deploy the mongos
, use the localhost exception to create the first user on the cluster.
Connect to the mongos
.
Use mongosh
to connect to the mongos
.
Create an administrative user.
Tip
Specify a different username for your sharded cluster administrative user than the usernames in your initial replica set.
Using different names avoids conflicts when restoring the users from the initial replica set to the sharded cluster.
The following db.createUser()
method creates a user
named admin01
with the clusterManager
and
restore
roles:
use admin db.createUser( { user: "admin01", pwd: passwordPrompt(), roles: [ { role: "clusterManager", db: "admin" }, { role: "restore", db: "admin" } ] } )
After you run the command, the database prompts you to enter a
password for the admin01
user.
4. Migrate the admin
Database from the Initial Replica Set
The admin
database contains user and system information. To migrate
the admin
database from your initial replica set to the sharded
cluster, perform the following steps.
5. Restart the Initial Replica Set as a Shard
In this example, your initial replica set is a three-member replica set. This step updates the initial replica set so that it can be added as a shard to your sharded cluster.
The replica set runs on these hosts:
mongodb0.example.net:27017
mongodb1.example.net:27017
mongodb2.example.net:27017
For sharded clusters, you must set the role for each
mongod
instance in the shard to shardsvr
. To specify
the server role, set the sharding.clusterRole
setting in the
mongod
configuration file.
Note
Connect to a member of your initial replica set.
Use mongosh
to connect to one of the members of your
initial replica set.
Determine the replica set's primary and secondaries.
Run rs.status()
to determine the primary and
secondaries:
rs.status()
In the command output, the
replSetGetStatus.members[n].stateStr
field indicates which
member is the primary and which members are secondaries.
Restart the secondaries with the --shardsvr
option.
Warning
This step requires some downtime for applications connected to the replica set secondaries.
After you restart a secondary, any applications that are
connected to that secondary return a
CannotVerifyAndSignLogicalTime
error until you perform the
steps in 6. Add the Initial Replica Set as a Shard.
You can also restart your application to stop it from receiving
CannotVerifyAndSignLogicalTime
errors.
Restart the primary with the --shardsvr
option.
Warning
This step requires some downtime for applications connected to the primary of the replica set.
After you restart the primary, any applications that are
connected to the primary return a
CannotVerifyAndSignLogicalTime
error until you perform the
steps in 6. Add the Initial Replica Set as a Shard.
You can also restart your application to stop it from receiving
CannotVerifyAndSignLogicalTime
errors.
6. Add the Initial Replica Set as a Shard
After you convert the initial replica set (rs0
) to a shard, add it
to the sharded cluster.
Add the shard.
To add a shard to the cluster, run the sh.addShard()
method:
sh.addShard( "rs0/mongodb0.example.net:27017,mongodb1.example.net:27017,mongodb2.example.net:27017" )
Warning
Once the new shard is active, mongosh
and other clients must
always connect to the mongos
instance. Do not connect
directly to the mongod
instances. If your clients connect to
shards directly, you may create data or metadata inconsistencies.
7. Update Your Application Connection String
After you add the first shard to your cluster, update the connection string used by your applications to the connection string for your sharded cluster. Then, restart your applications.
8. Deploy a Second Replica Set
Deploy a new replica set called rs1
. The members of replica set
rs1
are on the following hosts:
mongodb3.example.net
mongodb4.example.net
mongodb5.example.net
Connect to a replica set member.
Use mongosh
to connect to one of the replica set
members. For example:
Initiate the replica set.
In mongosh
, run the rs.initiate()
method to initiate a replica set that contains the current member:
rs.initiate( { _id : "rs1", members: [ { _id: 0, host: "mongodb3.example.net:27018" }, { _id: 1, host: "mongodb4.example.net:27018" }, { _id: 2, host: "mongodb5.example.net:27018" } ] } )
The preceding command requires the localhost exception to perform administrative actions without authentication.
Important
Run rs.initiate()
on just one and only one
mongod
instance for the replica set.
Add an administrative user for the replica set.
After you deploy the replica set, use the localhost exception to create the replica set's first user.
Determine the replica set primary.
To determine the primary, run rs.status()
:
rs.status()
In the command output, the
replSetGetStatus.members[n].stateStr
field indicates
which member is the primary.
Connect to the replica set primary.
Connect to the replica set primary with mongosh
.
For example, if the primary is mongodb4.example.net
, run
this command:
Create an administrative user.
Run the following db.createUser()
method to create
a user named rs1Admin
with the userAdmin
role:
use admin db.createUser( { user: "rs1Admin", pwd: passwordPrompt(), roles: [ { role: "userAdmin", db: "admin" } ] } )
After you run the command, the database prompts you to enter a
password for the rs1Admin
user.
9. Add the Second Replica Set to the Cluster as a Shard
Add the new replica set, rs1
, to the sharded cluster.
Add the second shard.
After you connect to the mongos
, add the replica set
rs1
as a shard to the cluster with the sh.addShard()
method:
sh.addShard( "rs1/mongodb3.example.net:27018,mongodb4.example.net:27018,mongodb5.example.net:27018" )
10. Shard a Collection
The final step of the procedure is to shard a collection in the sharded cluster.
Determine the shard key.
Determine the shard key for the collection. The shard key indicates how MongoDB distributes the documents between shards. Good shard keys:
Have values that are evenly distributed among all documents.
Group documents that are often accessed at the same time into contiguous chunks.
Allow for effective distribution of activity among shards.
For more information, see Choose a Shard Key.
This procedure uses the number
field as the shard key for
the test_collection
collection.
Shard the collection.
In the test
database, shard the test_collection
.
Specify number
as the shard key.
sh.shardCollection( "test.test_collection", { "number" : 1 } )
The next time that the balancer runs,
it redistributes chunks of documents between shards. As clients
insert additional documents into this collection, the
mongos
routes the documents to the appropriate
shard.
Tip
Schedule the balancing window
When the balancer redistributes chunks, it may negatively impact your application's performance. To minimize performance impact, you can specify when the balancer runs so it does not run during peak hours. To learn more, see Schedule the Balancing Window.
Learn More
For more sharding tutorials and procedures, see these pages: