Configure Behavior of Balancer Process in Sharded Clusters

The balancer is a process that runs on one of the mongos instances in a cluster and ensures that chunks are evenly distributed throughout a sharded cluster. In most deployments, the default balancer configuration is sufficient for normal operation. However, administrators might need to modify balancer behavior depending on application or operational requirements. If you encounter a situation where you need to modify the behavior of the balancer, use the procedures described in this document.

For conceptual information about the balancer, see Sharded Collection Balancing and Cluster Balancer.

Schedule a Window of Time for Balancing to Occur

You can schedule a window of time during which the balancer can migrate chunks, as described in the following procedures:

The mongos instances user their own local timezones to when respecting balancer window.

Configure Default Chunk Size

The default chunk size for a sharded cluster is 64 megabytes. In most situations, the default size is appropriate for splitting and migrating chunks. For information on how chunk size affects deployments, see details, see Chunk Size.

Changing the default chunk size affects chunks that are processes during migrations and auto-splits but does not retroactively affect all chunks.

To configure default chunk size, see Modify Chunk Size in a Sharded Cluster.

Change the Maximum Storage Size for a Given Shard

The maxSize field in the shards collection in the config database sets the maximum size for a shard, allowing you to control whether the balancer will migrate chunks to a shard. If mapped size [1] is above a shard’s maxSize, the balancer will not move chunks to the shard. Also, the balancer will not move chunks off an overloaded shard. This must happen manually. The maxSize value only affects the balancer’s selection of destination shards.

By default, maxSize is not specified, allowing shards to consume the total amount of available space on their machines if necessary.

You can set maxSize both when adding a shard and once a shard is running.

To set maxSize when adding a shard, set the addShard command’s maxSize parameter to the maximum size in megabytes. For example, the following command run in the mongo shell adds a shard with a maximum size of 125 megabytes:

db.runCommand( { addshard : "example.net:34008", maxSize : 125 } )

To set maxSize on an existing shard, insert or update the maxSize field in the shards collection in the config database. Set the maxSize in megabytes.


Assume you have the following shard without a maxSize field:

{ "_id" : "shard0000", "host" : "example.net:34001" }

Run the following sequence of commands in the mongo shell to insert a maxSize of 125 megabytes:

use config
db.shards.update( { _id : "shard0000" }, { $set : { maxSize : 125 } } )

To later increase the maxSize setting to 250 megabytes, run the following:

use config
db.shards.update( { _id : "shard0000" }, { $set : { maxSize : 250 } } )
[1]This value includes the mapped size of all data files including the``local`` and admin databases. Account for this when setting maxSize.

Require Replication During Chunk Migration (Secondary Throttle)

New in version 2.2.1: _secondaryThrottle became an option to the balancer and to moveChunk in 2.2.1. _secondaryThrottle makes it possible to require the balancer to wait for replication to secondaries for all documents during migrations.

Changed in version 2.4: _secondaryThrottle became the default mode for all balancer and moveChunk operations.

Before 2.2.1, the write operations required to migrate chunks between shards do not need to replicate to secondaries in order to succeed. However, you can configure the balancer to require write operations during the migration to replicate to secondaries. This throttles or slows the migration process and in doing so reduces the potential impact of migrations on a sharded cluster.

You can throttle migrations by enabling the balancer’s _secondaryThrottle parameter. When enabled, secondary throttle requires a { w : 2 } write concern on delete and insertion operations, so that every operation propagates to at least one secondary before the balancer issues the next operation.

Starting with version 2.4 the default secondaryThrottle value is true. To revert to previous behavior, set _secondaryThrottle to false.

You enable or disable _secondaryThrottle directly in the settings collection in the config database by running the following commands from a mongo shell, connected to a mongos instance:

use config
db.settings.update( { "_id" : "balancer" } , { $set : { "_secondaryThrottle" : false } } , { upsert : true } )

You also can enable secondary throttle when issuing the moveChunk command by setting _secondaryThrottle to true. For more information, see moveChunk.