Docs4dev
Docs
mongodb / v3.6 / reference / tutorial-deploy-shard-cluster.html

Deploy a Sharded Cluster

On this page

Overview

This tutorial involves creating a new sharded cluster that consists of a mongos, the config server replica set, and two shard replica sets.

Considerations

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

Tip

To avoid downtime, give each config server a logical DNS name (unrelated to the server’s physical or virtual hostname). Without logical DNS names, moving or renaming a config server requires shutting down every mongod and mongos instance in the sharded cluster.

Localhost Deployments

If you use either localhost or its IP address as the hostname portion of any host identifier, you must use that identifier as the host setting for any other MongoDB component in the cluster.

For example, the sh.addShard() method takes a host parameter for the hostname of the target shard. If you set host to localhost, you must then use localhost as the host for all other shards in the cluster.

Security

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

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

Procedure

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.

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
1

Start each member of the config server replica set.

When starting each mongod, specify the mongod settings either via 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 the hostname/ip address or comma-delimited list of hostnames or ip addresses that remote clients (including the other members of the config server replica set as well as other members of the sharded cluster) can use to connect to the instance.

    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.

  • 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:

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

For more information on startup parameters, see the mongod reference page.

2

Connect to one of the config servers.

Connect a mongo shell to one of the config server members.

mongo --host <hostname> --port <port>
3

Initiate the replica set.

From the mongo shell, 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 just one and only one mongod instance for the replica set.

rs.initiate(
  {
    _id: "<replSetName>",
    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 Replica Set Configuration for more information on replica set configuration documents.

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.

Note

Shard replica sets must not use the same name as the config server replica set.

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

1

Start each member of the shard replica set.

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

  • Configuration File
  • Command Line

If using a configuration file, set:

sharding:
    clusterRole: shardsvr
replication:
    replSetName: <replSetName>
net:
    bindIp: localhost,<ip address>

  • replication.replSetName to the desired name of the replica set,

  • sharding.clusterRole option to shardsvr,

  • net.bindIp option to the ip or a comma-delimited list of ips that remote clients (including the other members of the config server replica set as well as other members of the sharded cluster) can use to connect to the instance.

    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.

    </