Convert a Replica Set to a Sharded Cluster

Overview

This tutorial converts a single three-member replica set to a sharded cluster with two shards. Each shard is an independent three-member replica set. This tutorial is specific to MongoDB 3.6. For other versions of MongoDB, refer to the corresponding version of the MongoDB Manual.

The procedure is as follows:

  1. Create the initial three-member replica set and insert data into a collection. See Set Up Initial Replica Set.
  2. Start the config servers and a mongos. See Deploy Config Server Replica Set and mongos.
  3. Add the initial replica set as a shard. See Add Initial Replica Set as a Shard.
  4. Create a second shard and add to the cluster. See Add Second Shard.
  5. Shard the desired collection. See Shard a Collection.

Prerequisites

This tutorial uses a total of ten servers: one server for the mongos and three servers each for the first replica set, the second replica set, and the config server replica set.

Each server must have a resolvable domain, hostname, or IP address within your system.

The tutorial uses the default data directories (e.g. /data/db and /data/configdb). Create the appropriate directories with appropriate permissions. To use different paths, see Configuration File Options .

Procedures

Set Up Initial Replica Set

This procedure creates the initial three-member replica set rs0. The replica set members are on the following hosts: mongodb0.example.net, mongodb1.example.net, and mongodb2.example.net.

1

Start each member of the replica set with the appropriate options.

For each member, start a mongod instance with the following settings:

  • Set replication.replSetName option to the replica set name,

    If your application connects to more than one replica set, each set should have a distinct name. Some drivers group replica set connections by replica set name.

  • Set net.bindIp option to the ip or a comma-delimited list of ips, and

  • Set any other settings as appropriate for your deployment.

In this tutorial, the three mongod instances are associated with the following hosts:

Replica Set Member Hostname
Member 0 mongodb0.example.net
Member 1 mongodb1.example.net
Member 2 mongodb2.example.net

The following example specifies the replica set name and the ip binding through the --replSet and --bind_ip command-line options:

Warning

Before binding to a non-localhost (e.g. publicly accessible) IP address, ensure you have secured your cluster from unauthorized access. For a complete list of security recommendations, see Security Checklist. At minimum, consider enabling authentication and hardening network infrastructure.

mongod --replSet "rs0" --bind_ip localhost,<ip address of the mongod host>

For <ip address>, specify the ip address or hostname for your mongod instance that remote clients (including the other members of the replica set) can use to connect to the instance.

Alternatively, you can also specify the replica set name and the ip addresses in a configuration file:

replication:
   replSetName: "rs0"
net:
   bindIp: localhost,<ip address>

To start mongod with a configuration file, specify the configuration file’s path with the --config option:

mongod --config <path-to-config>

In production deployments, you can configure a init script to manage this process. Init scripts are beyond the scope of this document.

2

Connect a mongo shell to one of the mongod instances.

From the same machine where one of the mongod is running (in this tutorial, mongodb0.example.net), start the mongo shell. To connect to the mongod listening to localhost on the default port of 27017, simply issue:

mongo

Depending on your path, you may need to specify the path to the mongo binary.

3

Initiate the replica set.

From the mongo shell, run rs.initiate() on replica set member 0.

Important

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

rs.initiate( {
   _id : "rs0",
   members: [
      { _id: 0, host: "mongodb0.example.net:27017" },
      { _id: 1, host: "mongodb1.example.net:27017" },
      { _id: 2, host: "mongodb2.example.net:27017" }
   ]
})

MongoDB initiates a replica set, using the default replica set configuration.

4

Create and populate a new collection.

The following step adds one million documents to the collection test_collection and can take several minutes depending on your system.

To determine the primary, use rs.status().

Issue the following operations on the primary of the replica set:

use test
var bulk = db.test_collection.initializeUnorderedBulkOp();
people = ["Marc", "Bill", "George", "Eliot", "Matt", "Trey", "Tracy", "Greg", "Steve", "Kristina", "Katie", "Jeff"];
for(var i=0; i<1000000; i++){
   user_id = i;
   name = people[Math.floor(Math.random()*people.length)];
   number = Math.floor(Math.random()*10001);
   bulk.insert( { "user_id":user_id, "name":name, "number":number });
}
bulk.execute();

For more information on deploying a replica set, see Deploy a Replica Set.

Restart the Replica Set as a Shard

Changed in version 3.4: For MongoDB 3.4 sharded clusters, mongod instances for the shards must explicitly specify its role as a shardsvr, either via the configuration file setting sharding.clusterRole or via the command line option --shardsvr.

Note

Default port for mongod instances with the shardsvr role is 27018. To use a different port, specify net.port setting or --port option.

1

Determine the primary and secondary members.

Connect a mongo shell to one of the members and run rs.status() to determine the primary and secondary members.

2

Restart secondary members with the --shardsvr option.

One secondary at a time, restart each secondary with the --shardsvr option. To continue to use the same port, include the