Start a Sharded Cluster with a Config Shard

Create the Config Server Replica Set.

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

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

1. 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.

   Configuration File

   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.

2. Connect mongosh to one of the config server members.

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

3. 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.

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

mongos --config <path-to-config>

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

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
} )

Confirm Cluster uses a Config Shard

To confirm that the sharded cluster now uses the config shard, run the serverStatus command to check that the configServerInShardCache status returns true:

db.adminCommand( {
   serverStatus: 1,
} ).shardingStatistics.configServerInShardCache

true