addShardToZone

Definition

  • addShardToZone

New in version 3.4: Associates a shard with a zone. MongoDB associates this shard withthe given zone. Chunks that are covered by the zone are assigned to shardsassociated 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:

  1. {
  2.   addShardToZone: <string>,
  3.   zone: <string>
  4. }

The command takes the following fields:

FieldTypeDescriptionaddShardtoZonestringThe name of the shard to associate with the zone.zonestringThe name of the zone to associate with the shard.

Only issue addShardToZone when connected to amongos instance.

The mongo shell provides the helper methodsh.addShardToZone()

Behavior

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

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

Ranges

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

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

Starting in MongoDB 4.0.2, you can runupdateZoneKeyRange database command and its helperssh.updateZoneKeyRange() and sh.addTagRange() onan unsharded collection or a non-existing collection.

Tip

Changed in version 4.0.3: By defining the zones and the zone ranges before sharding an emptyor a non-existing collection, the shard collection operation createschunks for the defined zone ranges as well as any additional chunksto cover the entire range of the shard key values and performs aninitial chunk distribution based on the zone ranges. This initialcreation and distribution of chunks allows for faster setup of zonedsharding. After the initial distribution, the balancer manages thechunk distribution going forward.

See Pre-Define Zones and Zone Ranges for an Empty or Non-Existing Collection for an example.

Security

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

The clusterAdmin or clusterManager built-in roles havethe appropriate permissions for issuing addShardToZone. See thedocumentation page for Role-Based Access Control formore information.

Example

The following example associates shard0000 with zone JFK:

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

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

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

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