Deploy a Sharded Cluster

Connectivity

Each member of a sharded cluster must be able to connect to all other members in the cluster. This includes all shards and config servers. Ensure that network and security systems, including all interface and firewalls, allow these connections.

Hostnames and Configuration

Security

This tutorial does not include the required steps for configuring Internal/Membership Authentication or Role-Based Access Control.

In production environments, sharded clusters should employ at minimum x.509 security for internal authentication and client access.

Create the Config Server Replica Set

The following steps deploys a config server replica set.

For a production deployment, deploy a config server replica set with at least three members. For testing purposes, you can create a single-member replica set.

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

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

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

Once the config server replica set (CSRS) is initiated and up, proceed to creating the shard replica sets.

Create the Shard Replica Sets

For a production deployment, use a replica set with at least three members. For testing purposes, you can create a single-member replica set.

For each shard, use the following steps to create the shard replica set:

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

rs.initiate(
  {
    _id : "myReplSet",
    members: [
      { _id : 0, host : "s1-mongo1.example.net:27018" },
      { _id : 1, host : "s1-mongo2.example.net:27018" },
      { _id : 2, host : "s1-mongo3.example.net:27018" }
    ]
  }
)

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.

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>

Once you have connected mongosh to the mongos, continue to the next procedure to add shards to the cluster.

Add Shards to the Cluster

In a mongosh session that is connected to the mongos, use the sh.addShard() method to add each shard to the cluster.

The following operation adds a single shard replica set to the cluster:

sh.addShard( "<replSetName>/s1-mongo1.example.net:27018,s1-mongo2.example.net:27018,s1-mongo3.example.net:27018")

Repeat these steps until the cluster includes all desired shards.

Enable Sharding for a Database

Before you can shard a collection, you must enable sharding for the collection's database. Enabling sharding for a database does not redistribute data but make it possible to shard the collections in that database.

From a mongosh session that is connected to the mongos, use the sh.enableSharding() method to enable sharding on the target database. Enabling sharding on a database makes it possible to shard collections within a database.

sh.enableSharding("<database>")

Once you enable sharding for a database, MongoDB assigns a primary shard for that database where MongoDB stores all data in that database.

Shard a Collection

To shard a collection, connect mongosh to the mongos and use the sh.shardCollection() method.

MongoDB provides two strategies to shard collections:

• Hashed sharding uses a hashed index of a single field as the shard key to partition data across your sharded cluster.

  sh.shardCollection("<database>.<collection>", { <shard key field> : "hashed" } )

• Range-based sharding can use multiple fields as the shard key and divides data into contiguous ranges determined by the shard key values.

  sh.shardCollection("<database>.<collection>", { <shard key field> : 1, ... } )

Shard Key Considerations

Your selection of shard key affects the efficiency of sharding, as well as your ability to take advantage of certain sharding features such as zones. To learn how to choose an effective shard key, see Choose a Shard Key.

Starting in version 4.0, mongosh provides the method convertShardKeyToHashed(). This method uses the same hashing function as the hashed index and can be used to see what the hashed value would be for a key.