Navigation
This version of the manual is no longer supported.

Manage the Config Servers

Config servers store all cluster metadata, most importantly, the mapping from chunks to shards. This section provides an overview of the basic procedures to migrate, replace, and maintain these servers.

This page includes the following:

Deploy Three Config Servers for Production Deployments

For redundancy, all production sharded clusters should deploy three config servers processes on three different machines.

Do not use only a single config server for production deployments. Only use a single config server deployments for testing. You should upgrade to three config servers immediately if you are shifting to production. The following process shows how to convert a test deployment with only one config server to production deployment with three config servers.

  1. Shut down all existing MongoDB processes in the cluster. This includes:

  2. Copy the entire dbpath file system tree from the existing config server to the two machines that will provide the additional config servers. These commands, issued on the system with the existing Config Database Contents, mongo-config0.example.net may resemble the following:

    rsync -az /data/configdb mongo-config1.example.net:/data/configdb
    rsync -az /data/configdb mongo-config2.example.net:/data/configdb
    
  3. Start all three config servers, using the same invocation that you used for the single config server.

    mongod --configsvr
    
  4. Restart all shard mongod and mongos processes.

Migrate Config Servers with the Same Hostname

Use this process when you need to migrate a config server to a new system but the new system will be accessible using the same host name.

  1. Shut down the config server that you’re moving.

    This will render all config data for your cluster read only.

  2. Change the DNS entry that points to the system that provided the old config server, so that the same hostname points to the new system.

    How you do this depends on how you organize your DNS and hostname resolution services.

  3. Move the entire dbpath file system tree from the old config server to the new config server. This command, issued on the old config server system, may resemble the following:

    rsync -az /data/configdb mongo-config0.example.net:/data/configdb
    
  4. Start the config instance on the new system. The default invocation is:

    mongod --configsvr
    

When you start the third config server, your cluster will become writable and it will be able to create new splits and migrate chunks as needed.

Migrate Config Servers with Different Hostnames

Use this process when you need to migrate a Config Database Contents to a new server and it will not be accessible via the same hostname. If possible, avoid changing the hostname so that you can use the previous procedure.

  1. Disable the cluster balancer process temporarily. See Disable the Balancer for more information.

  2. Shut down the config server you’re moving.

    This will render all config data for your cluster “read only:”

    rsync -az /data/configdb mongodb.config2.example.net:/data/configdb
    
  3. Start the config instance on the new system. The default invocation is:

    mongod --configsvr
    
  4. Shut down all existing MongoDB processes. This includes:

  5. Restart all mongod processes that provide the shard servers.

  6. Update the --configdb parameter (or configdb) for all mongos instances and restart all mongos instances.

  7. Re-enable the balancer to allow the cluster to resume normal balancing operations. See the Disable the Balancer section for more information on managing the balancer process.

Replace a Config Server

Use this procedure only if you need to replace one of your config servers after it becomes inoperable (e.g. hardware failure.) This process assumes that the hostname of the instance will not change. If you must change the hostname of the instance, use the process for migrating a config server to a different hostname.

  1. Disable the cluster balancer process temporarily. See Disable the Balancer for more information.

  2. Provision a new system, with the same hostname as the previous host.

    You will have to ensure that the new system has the same IP address and hostname as the system it’s replacing or you will need to modify the DNS records and wait for them to propagate.

  3. Shut down one (and only one) of the existing config servers. Copy all this host’s dbpath file system tree from the current system to the system that will provide the new config server. This command, issued on the system with the data files, may resemble the following:

    rsync -az /data/configdb mongodb.config2.example.net:/data/configdb
    
  4. Restart the config server process that you used in the previous step to copy the data files to the new config server instance.

  5. Start the new config server instance. The default invocation is:

    mongod --configsvr
    
  6. Re-enable the balancer to allow the cluster to resume normal balancing operations. See the Disable the Balancer section for more information on managing the balancer process.

Note

In the course of this procedure never remove a config server from the configdb parameter on any of the mongos instances. If you need to change the name of a config server, always make sure that all mongos instances have three config servers specified in the configdb setting at all times.

Backup Cluster Metadata

The cluster will remain operational [1] without one of the config database’s mongod instances, creating a backup of the cluster metadata from the config database is straight forward:

  1. Disable the cluster balancer process temporarily. See Disable the Balancer for more information.
  2. Shut down one of the config databases.
  3. Create a full copy of the data files (i.e. the path specified by the dbpath option for the config instance.)
  4. Restart the original configuration server.
  5. Re-enable the balancer to allow the cluster to resume normal balancing operations. See the Disable the Balancer section for more information on managing the balancer process.
[1]While one of the three config servers is unavailable, the cluster cannot split any chunks nor can it migrate chunks between shards. Your application will be able to write data to the cluster. The Config Servers section of the documentation provides more information on this topic.