Navigation

addShardToZone

Definition

addShardToZone

New in version 3.4: Associates a shard with a zone. MongoDB associates this shard with the given zone. Chunks that are covered by the zone are assigned to shards associated with the zone.

To run addShardToZone, use the db.runCommand( { <command> } ) method.

You must run addShardToZone on the admin database.

The addShardToZone command has the following syntax:

{
  addShardToZone: <string>,
  zone: <string>
}

The command takes the following fields:

Field Type Description
addShardtoZone string The name of the shard to associate with the zone.
zone string The name of the zone to associate with the shard.

Only issue addShardToZone when connected to a mongos instance.

The mongo shell provides the helper method sh.addShardToZone()

Behavior

You can associate a zone with multiple shards, and a shard can associate with multiple zones.

See the zone manual page for more information on zones in a sharded cluster.

Ranges

MongoDB effectively ignores zones that do not have at least one range of shard key values associated with it.

To associate a range of shard key values with a zone, use the updateZoneKeyRange database command, or the sh.updateZoneKeyRange() shell helper.

Security

For sharded clusters running with authentication, you must authenticate as a user whose privileges include update on the config.shards collection or the config database.

The clusterAdmin or clusterManager built-in roles have the appropriate permissions for issuing addShardToZone. See the documentation page for Role-Based Access Control for more information.

Example

The following example associates shard0000 with zone JFK:

admin = db.getSiblingDB("admin")
admin.runCommand( { addShardToZone : "shard0000" , zone : "JFK" } )

A shard can associate with multiple zones. The following example associates LGA to shard0000:

admin = db.getSiblingDB("admin")
admin.runCommand( { addShardToZone : "shard0000" , zone : "LGA" } )

shard0000 associates with both the LGA zone and the JFK zone. In a balanced cluster, MongoDB routes reads and writes covered by either zone to shard0000.