Start a Sharded Cluster with a Config Shard

On this page

About this Task

Steps
Learn More

Starting in MongoDB 8.0, you can configure a config server to store your application data in addition to the usual sharded cluster metadata. A mongod node that provides both config server and shard server functionality is called a config shard. A mongod node that runs as a standalone --configsvr without shard server functionality is called a dedicated config server.

About this Task

You can consider using a config shard if your cluster has three or fewer shards.

For details, see Config Shard Use Cases.

Compatibility

You can perform this task on deployments hosted in the following environments:

MongoDB Atlas: The fully managed service for MongoDB deployments in the cloud

Note

This task is not available on the Atlas Shared Tier or on Atlas Serverless.

MongoDB Enterprise: The subscription-based, self-managed version of MongoDB
MongoDB Community: The source-available, free-to-use, and self-managed version of MongoDB

Steps

Create the Config Server Replica Set.

For a production deployment, deploy a config server replica set with at least three members.

Note

The config server replica set must not use the same name as any of the shard replica sets.

For this tutorial, the config server replica set members are associated with the following hosts:

Config Server Replica Set Member	Hostname
Member 0	`cfg1.example.net`
Member 1	`cfg2.example.net`
Member 2	`cfg3.example.net`

Start each member of the config server replica set.

When starting each mongod, specify the mongod settings using either a configuration file or the command line.

If using a configuration file, set:

sharding:
  clusterRole: configsvr
replication:
  replSetName: <replica set name>
net:
  bindIp: localhost,<hostname(s)|ip address(es)>

sharding.clusterRole to configsvr.
replication.replSetName to the desired name of the config server replica set.
net.bindIp option to one of:
- The hostname/ip address.
- A comma-delimited list of hostnames or ip addresses that remote clients can use to connect to the instance (including the other members of the config server replica set as well as other members of the sharded cluster).
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.
Additional settings as appropriate to your deployment, such as storage.dbPath and net.port. For more information on the configuration file, see configuration options.

Start the mongod with the --config option set to the configuration file path.

mongod --config <path-to-config-file>

If using the command line options, start the mongod with the --configsvr, --replSet, --bind_ip, and other options as appropriate to your deployment. For example:

mongod --configsvr --replSet <replica set name> --dbpath <path> --bind_ip localhost,<hostname(s)|ip address(es)>

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 startup parameters, see the mongod reference page.

Connect mongosh to one of the config server members.
```
mongosh --host <hostname> --port <port>
```

Initiate the replica set.

From mongosh, run the rs.initiate() method.

rs.initiate() can take an optional replica set configuration document. In the replica set configuration document, include:

The _id set to the replica set name specified in either the replication.replSetName or the --replSet option.
The configsvr field set to true for the config server replica set.
The members array with a document per each member of the replica set.

Important

Run rs.initiate() on only one mongod instance for the replica set.

rs.initiate(
  {
    _id: "myReplSet",
    configsvr: true,
    members: [
      { _id : 0, host : "cfg1.example.net:27019" },
      { _id : 1, host : "cfg2.example.net:27019" },
      { _id : 2, host : "cfg3.example.net:27019" }
    ]
  }
)

See Self-Managed Replica Set Configuration for more information on replica set configuration documents.

Start a mongos for the Sharded Cluster.

Start a mongos using either a configuration file or a command line parameter to specify the config servers.

If using a configuration file, set the sharding.configDB to the config server replica set name and at least one member of the replica set in <replSetName>/<host:port> format.

Warning

sharding:
  configDB: <configReplSetName>/cfg1.example.net:27019,cfg2.example.net:27019
net:
  bindIp: localhost,<hostname(s)|ip address(es)>

Start the mongos specifying the --config option and the path to the configuration file.

mongos --config <path-to-config>

For more information on the configuration file, see configuration options.

If using command line parameters start the mongos and specify the --configdb, --bind_ip, and other options as appropriate to your deployment. For example:

Warning

mongos --configdb <configReplSetName>/cfg1.example.net:27019,cfg2.example.net:27019,cfg3.example.net:27019 --bind_ip localhost,<hostname(s)|ip address(es)>

Include any other options as appropriate for your deployment.

At this point, your sharded cluster consists of the mongos and the config servers. You can now connect to the sharded cluster using mongosh.

Connect to the Sharded Cluster.

Connect mongosh to the mongos. Specify the host and port on which the mongos is running:

mongosh --host <hostname> --port <port>

Transition from a Dedicated Config Server to a Config Shard.

This example configures a dedicated config server to run as a config shard:

db.adminCommand( {
   transitionFromDedicatedConfigServer: 1
} )

Learn More

Back

Config Shard

Reference