Restart a Sharded Cluster

The tutorial is specific to MongoDB 4.2. For earlier versions ofMongoDB, refer to the corresponding version of the MongoDB Manual.

This procedure demonstrates the shutdown and startup sequence for restartinga sharded cluster. Stopping or starting the components of a sharded clusterin a different order may cause communication errors between members. Forexample, shard servers may appear to hangif there are no config serversavailable.

Important

This procedure should only be performed during a plannedmaintenance period. During this period, applications should stopall reads and writes to the cluster in order to prevent potentialdata loss or reading stale data.

Disable the Balancer

Disable the balancer to stop chunk migration and do not perform any metadatawrite operations until the process finishes. If a migration is inprogress, the balancer will complete the in-progress migration beforestopping.

To disable the balancer, connect to one of the cluster’smongos instances and issue the following command: [1]

  1. sh.stopBalancer()

To check the balancer state, issue the sh.getBalancerState()command.

For more information, see Disable the Balancer.

[1]Starting in MongoDB 4.2, sh.stopBalancer() also disablesauto-splitting for the sharded cluster.

Stop Sharded Cluster

Stop mongos routers.

Run db.shutdownServer() from the admin database on eachmongos router:

  1. use admin
  2. db.shutdownServer()

Stop each shard replica set.

Run db.shutdownServer() from the admin database on eachshard replica set member to shutdownits mongod process. Shutdown all secondary membersbefore shutting down the primary in each replica set.

Stop config servers.

Run db.shutdownServer() from the admin database on eachof the config servers toshutdown its mongod process. Shutdown allsecondary members before shutting down the primary.

Start Sharded Cluster

Start config servers.

When starting each mongod, specify themongod settings using either a configuration file or thecommand line. For more information on startup parameters, see themongod reference page.

Configuration File

If using a configuration file, start the mongod withthe —config option set to the configuration file path.

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

Command Line

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

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

After starting all config servers, connect to the primarymongod and run rs.status() to confirm thehealth and availability of each CSRS member.

Start each shard replica set.

When starting each mongod, specify themongod settings using either a configuration file or thecommand line.

Configuration File

If using a configuration file, start the mongod withthe —config option set to the configuration file path.

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

Command Line

If using the command line option, start the mongod withthe —replSet, —shardsvr, and —bind_ip options,and other options as appropriate to your deployment. For example:

  1. mongod --shardsvr --replSet <replSetname> --dbpath <path> --bind_ip localhost,<hostname(s)|ip address(es)>

After starting all members of each shard, connect to each primarymongod and run rs.status() to confirm the healthand availability of each member.

Start mongos routers.

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

Configuration File

If using a configuration file, start the mongos specifyingthe —config option and the path to the configuration file.

  1. mongos --config <path-to-config>

For more information on the configuration file, seeconfiguration options.

Command Line

If using command line parameters, start the mongos and specifythe —configdb, —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 unauthorizedaccess. For a complete list of security recommendations, seeSecurity Checklist. At minimum, considerenabling authentication andhardening network infrastructure.

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

Include any other options as appropriate for your deployment.

Re-Enable the Balancer

Re-enable the balancer to resumechunk migrations.

Connect to one of the cluster’s mongos instances and runthe sh.startBalancer() command: [2]

  1. sh.startBalancer()

To check the balancer state, issue the sh.getBalancerState()command.

For more information, see Enable the Balancer.

[2]Starting in MongoDB 4.2, sh.startBalancer() also enablesauto-splitting for the sharded cluster.

Validate Cluster Accessibility

Connect a mongo shell to one of the cluster’smongos processes. Use sh.status()to check the overall cluster status.

To confirm that all shards are accessible and communicating, inserttest data into a temporary sharded collection. Confirm that data isbeing split and migrated between each shard in your cluster. You canconnect a mongo shell to each shard primary anduse db.collection.find() to validate that the data wassharded as expected.

Important

To prevent potential data loss or reading stale data,do not start application reads and writes to the clusteruntil after confirming the cluster is healthy and accessible.