Navigation

Modify a Cluster

Note

Groups and projects are synonymous terms. Your {GROUP-ID} is the same as your project ID. For existing groups, your group/project ID remains the same. The resource and corresponding endpoints use the term groups.

Note

This feature is not available for M0 (Free Tier) clusters, and has limited functionality for M2 and M5 clusters. For more information, see Atlas M0 (Free Tier), M2, and M5 Limitations.

The Atlas API uses HTTP Digest Authentication. Provide your Atlas username and API key as the username and password when constructing the HTTP request.

For complete documentation on configuring API access for an Atlas project, see Configure Atlas API Access.

Base URL: https://cloud.mongodb.com/api/atlas/v1.0

Syntax

PATCH /groups/{GROUP-ID}/clusters/{CLUSTER-NAME}

Request Path Parameters

Path Parameter Type Necessity Description
GROUP-ID string Required Unique identifier for the project containing the cluster.
CLUSTER-NAME string Required Name of the cluster to modify.

Request Body Parameters

Important

If modifying any of the providerSettings or replicationSpec values, you must specify the providerSettings.providerName. For M2 and M5 clusters, you must also specify the providerSettings.backingProviderName.

You cannot modify a paused cluster other than to resume the cluster. Nor can you pause a cluster with pending changes.

You do not need to provide all parameters when modifying a cluster, only the parameters you want to change and any parameters required to make that change.

Body Parameter Type Necessity Description
autoScaling document Optional Contains the diskGBEnabled field which specifies whether to enable or disable disk auto-scaling.
autoScaling
.diskGBEnabled
boolean Optional

Specifies whether disk auto-scaling is enabled. The default is true.

  • Set to true to enable disk auto-scaling.
  • Set to false to disable disk auto-scaling.

Note

Disk auto-scaling is subject to limitations based on the maximum amount of RAM for the selected cluster tier and the oplog size. See Customize Your Storage for details.

backupEnabled boolean Optional

Set to true to enable Atlas continuous backups for the cluster.

Set to false to disable continuous backups for the cluster. Atlas deletes any stored snapshots. See the continuous backup Snapshot Schedule for more information.

You cannot enable continuous backups if you have an existing cluster in the project with Cloud Provider Snapshots enabled.

The default value is false.

biConnector document Optional

Specify whether to enable/disable BI Connector for Atlas.

BI Connector for Atlas is only available for M10+ clusters.

biConnector.enabled boolean Optional

Specifies whether or not BI Connector for Atlas is enabled on the cluster.

  • Set to true to enable BI Connector for Atlas.
  • Set to false to disable BI Connector for Atlas.
biConnector.readPreference string Optional

Specifies the read preference to be used by BI Connector for Atlas on the cluster. Each BI Connector for Atlas read preference contains a distinct combination of readPreference and readPreferenceTags options. For details on BI Connector for Atlas read preferences, refer to the BI Connector Read Preferences Table.

  • Set to "primary" to have BI Connector for Atlas read from the primary.

  • Set to "secondary" to have BI Connector for Atlas read from a secondary member. Default if there are no analytics nodes in the cluster.

  • Set to "analytics" to have BI Connector for Atlas read from an analytics node. Default if the cluster contains analytics nodes.

    Note

    To set the readPreference value to "analytics", the cluster must have at least one analytics node.

    If the readPreference value is analytics, you cannot remove all analytics nodes from the cluster.

clusterType string Conditional

Specifies the type of the cluster that you want to modify.

You cannot convert a sharded cluster deployment to a replica set deployment.

When should you use clusterType?

Condition Necessity
You set replicationSpecs. Required
You are deploying Global Clusters. Required
You are deploying non-Global replica sets and sharded clusters. Optional

Accepted values include:

Value Cluster Type
REPLICASET replica set
SHARDED sharded cluster
GEOSHARDED Global Cluster
diskSizeGB double Conditional

When should you use diskSizeGB?

This setting:

  • Cannot be used with clusters with local NVMe SSDs
  • Cannot be used with Azure clusters
  • Must be used when replicationSpecs is set

The size in gigabytes of the server’s root volume. You can add capacity by increasing this number, up to a maximum possible value of 4096 (i.e., 4 TB).

Each instance size has its own default value. If you set a value below the instance default, Atlas replaces it with the default value. To view default values: open the Atlas web interface; click the button to add a new cluster; view the available default sizes; close the window without saving changes.

Important

Atlas calculates storage charges differently depending on whether you choose the default value or a custom value. For details, see Storage Capacity.

Note

The maximum value for disk storage cannot exceed 50 times the maximum RAM for the selected cluster tier. If you require additional storage space beyond this limitation, consider upgrading your cluster to a higher tier.

encryptionAtRestProvider string Optional

Set the Encryption at Rest parameter to one of the following:

Specify AWS to enable Encryption at Rest using the Atlas project AWS Key Management System settings. The cluster must meet the following requirements:

Parameter Requirement
providerSettings
.instanceSizeName
M10 or greater
backupEnabled false or omitted

For complete documentation on Encryption at Rest restrictions, see Restrictions.

You must configure encryption at rest for the Atlas project before enabling it on any cluster in the project. For complete documentation on configuring Encryption at Rest, see Encryption at Rest Using Your Key Management.

Specify AZURE to enable Encryption at Rest using the Atlas project Azure Key Management System settings. The cluster must meet the following requirements:

Parameter Requirement
providerSettings
.instanceSizeName
M10 or greater
backupEnabled false or omitted

For complete documentation on Encryption at Rest restrictions, see Restrictions.

You must configure encryption at rest for the Atlas project before enabling it on any cluster in the project. For complete documentation on configuring Encryption at Rest, see Encryption at Rest Using Your Key Management.

Specify GCP to enable Encryption at Rest using the Atlas project GCP Key Management System settings. The cluster must meet the following requirements:

Parameter Requirement
providerSettings
.instanceSizeName
M10 or greater
backupEnabled false or omitted

For complete documentation on Encryption at Rest restrictions, see Restrictions.

You must configure encryption at rest for the Atlas project before enabling it on any cluster in the project. For complete documentation on configuring Encryption at Rest, see Encryption at Rest Using Your Key Management.

Specify NONE to disable Encryption at rest.

name string Optional Name of the cluster as it appears in Atlas. Once the cluster is created, its name cannot be changed.
mongoDBMajorVersion string Optional

Version of the cluster to deploy. Atlas supports the following MongoDB versions for M10+ clusters:

  • 3.4
  • 3.6
  • 4.0

You must set this value to 4.0 if providerSettings.instanceSizeName is either M2 or M5.

Atlas always deploys the cluster with the latest stable release of the specified version. You can upgrade to a newer version of MongoDB when you modify a cluster

numShards integer Optional

Selects whether the cluster is a replica set or a sharded cluster.

If this is set to 1, the cluster is a replica set. For more information on MongoDB replica sets, see Replication in the MongoDB manual.

If this is set to 2 or higher, the cluster is a sharded cluster with the number of shards specified. For more information on sharded clusters, see Sharding in the MongoDB manual.

For details on how this setting affects costs, see Number of Servers.

The possible values are 1 through 50, inclusive. The default value is 1.

Note

Do not include in the request body for Global Clusters.

paused boolean Optional

Indicates whether the cluster is paused or not. The default value is false.

You cannot create a paused cluster. Either omit the field or explicitly set to false.

providerBackupEnabled boolean Conditional

Set true or false to enable or disable Cloud Provider Snapshots for cluster backups. If providerBackupEnabled and backupEnabled are false, the cluster does not use Atlas backups.

If you disable continuous backups for the cluster, Atlas deletes all stored snapshots. See the continuous backup Snapshot Schedule for more information.

You cannot enable cloud provider snapshots if you have an existing cluster in the project with Continuous Backups enabled.

Important

You must set this value to true for NVMe clusters.

providerSettings document Optional Configuration for the provisioned servers on which MongoDB runs. The available options are specific to the cloud service provider.
providerSettings
.backingProviderName
string Conditional

Cloud service provider on which the server for a multi-tenant cluster is provisioned.

This setting is only valid when providerSetting.providerName is TENANT and providerSetting.instanceSizeName is M2 or M5.

The possible values are:

  • AWS - Amazon AWS
  • GCP - Google Cloud Platform
  • AZURE - Microsoft Azure
providerSettings
.diskIOPS
integer AWS Optional

Note

Requires that providerSettings.instanceSizeName be M30 or greater.

Note

This option is not available for clusters with local NVMe SSDs.

The maximum input/output operations per second (IOPS) the system can perform. The possible values depend on the selected providerSettings.instanceSizeName and diskSizeGB.

To view the possible range of IOPS values for the selected instance size and storage capacity:

  1. Open the Atlas web interface.
  2. Select Build a New Cluster.
  3. Under Cloud Provider & Region, select AWS.
  4. Under Cloud Provider & Region, select the region corresponding to your configured providerSettings.regionName.
  5. Under Cluster Tier, select the instance size corresponding to your configured providerSettings.instanceSizeName.
  6. Under Cluster Tier, set the Storage Capacity slider to your configured diskSizeGB. Alternatively, input the exact value of diskSizeGB in the input box to the right of the slider.

You can see the available IOPS range by checking the Provision IOPS box.

Note

If you set the diskIOPS value to a value higher than the default value for the selected volume size, Atlas automatically sets providerSettings.volumeType to PROVISIONED. If you manually set diskIOPS to the default value, you must specify providerSettings.volumeType to be either PROVISIONED or STANDARD.

The default value for providerSettings.diskIOPS is the same as the instance size’s Standard IOPS value, as viewable in the Atlas interface.

Changing this value affects the cost of running the cluster as described in the billing documentation.

providerSettings
.diskTypeName
string Azure Optional

Azure disk type of the server’s root volume.

The following table lists the possible values for this field, and their corresponding storage size.

diskTypeName Storage Size
P4 1 32GB
P6 64GB
P10 2 128GB
P20 512GB
P30 1024GB
P40 2048GB
P50 4095GB

1 Default for M20 and M30 Azure instances

2 Default for M40+ Azure instances

providerSettings
.encryptEBSVolume
boolean AWS Optional

If enabled, the Amazon EBS encryption feature encrypts the server’s root volume for both data at rest within the volume and for data moving between the volume and the instance.

Note

This setting is always enabled for clusters with local NVMe SSDs.

The default value is true.

providerSettings
.instanceSizeName
string Required

Atlas provides different instance sizes, each with a default storage capacity and RAM size. The instance size you select is used for all the data-bearing servers in your cluster. For definitions of data-bearing servers, see Number of Servers.

Atlas supports the following instance sizes. Atlas supports deploying M2 and M5 instances into a subset of available regions. The documentation for providersettings.regionName includes a list of these regions.

Instance sizes with _NVME appended (for example: M40_NVME) use locally attached NVMe storage for exceptional performance with the most IO-intensive workloads.

Instance Size Default Storage Default RAM
M2 2GB Shared
M5 5GB Shared
M10 10GB 2GB
M20 20GB 4GB
M30 40GB 8GB
M40 or R40 80GB 16GB
M40_NVME 380GB 15.25GB
M50 or R50 160GB 32GB
M50_NVME 760GB 30.5GB
M60 or R60 320GB 64GB
M60_NVME 1.6TB 61GB
R80 750GB 122GB
M80_NVME 1.6TB 122GB
M100 1TB 160GB
M140 1 1TB 192GB
M200 or R200 1.5TB 256GB
M200_NVME 3.1TB 244GB
M300 1 2TB 384GB
R400 3TB 488GB
M400_NVME 2 4TB 512GB

1 Only available if providerSettings.regionName is EU-WEST-3 (Paris).

2 Available only in the following regions:

  • US_EAST_1
  • US_EAST_2
  • US_WEST_2
  • EU_WEST_1
  • EU_CENTRAL_1
  • AP_NORTHEAST_1
Instance Size Default Storage Default RAM
M2 2GB Shared
M5 5GB Shared
M10 10GB 1.70GB
M20 20GB 3.75GB
M30 40GB 7.5GB
M40 80GB 15GB
M50 160GB 30GB
M60 320GB 60GB
M80 750GB 120GB
M200 1 1.5TB 240GB
M300 1 2.2TB 360GB

1 Not available if providerSettings.regionName is SOUTH_AMERICA_EAST_1 , EUROPE_WEST_3, NORTHEASTERN_ASIA_PACIFIC, or AUSTRALIA_SOUTHEAST_1

Instance Size Default Storage Default RAM
M2 2GB Shared
M5 5GB Shared
M10 32GB 2GB
M20 32GB 4GB
M30 32GB 8GB
M40 128GB 16GB
M50 128GB 32GB
M60 128GB 64GB
M80 256GB 128GB
M200 256GB 256GB

Important

M2 and M5 instance sizes are multi-tenant deployments. You must set providerSettings.providerName to TENANT and specify the cloud service provider in providerSettings.backingProviderName.

providerSettings
.providerName
string Optional

Cloud service provider on which the servers are provisioned.

The possible values are:

  • AWS - Amazon AWS
  • GCP - Google Cloud Platform
  • AZURE - Microsoft Azure
  • TENANT - A multi-tenant deployment on one of the supported cloud service providers. Only valid when providerSettings.instanceSizeName is either M2 or M5.

Important

M2 and M5 instance sizes are multi-tenant deployments. You must set providerSettings.providerName to TENANT and specify the cloud service provider in providerSettings.backingProviderName.

providerSettings
.regionName
string Optional

Required if setting replicationSpecs array to empty

This field is required if you have not set any values in the replicationSpecs array.

Physical location of your MongoDB cluster. The region you choose can affect network latency for clients accessing your databases.

Do not specify this field when creating a multi-region cluster using the replicationSpec document.

During deployment of an M10+ dedicated paid cluster, Atlas creates a VPC for the selected provider and region or regions if no existing VPC or VPC peering connection exists for that provider and region. Atlas assigns the VPC a Classless Inter-Domain Routing (CIDR) block.

For clusters deployed on AWS, if you want to create a VPC peering connection to an AWS VPC and require a specific CIDR block for a given region, you must create a VPC connection before deploying the cluster. See Set up VPC Peering Connection for for complete documentation on VPC peering connections.

Important

Multi-region clusters require one VPC peering connection for each region. MongoDB nodes can use only the peering connection that resides in the same region as the nodes to communicate with the peered VPC.

Select your cloud provider’s tab for example cluster region names:

  • US_EAST_1
  • US_WEST_2
  • EU_WEST_1

For a complete list of supported AWS regions, see Amazon Web Services (AWS).

  • CENTRAL_US
  • WESTERN_EUROPE
  • EASTERN_ASIA_PACIFIC

For a complete list of supported GCP regions, see Google Cloud Platform (GCP).

  • US_EAST_2
  • US_WEST
  • EUROPE_NORTH

For a complete list of supported Azure regions, see Microsoft Azure.

providerSettings
.volumeType
string AWS Optional

Possible values are:

Volume Type providerSettings.diskIOPS Value
STANDARD Must not exceed the default IOPS rate for the selected volume size.
PROVISIONED Must fall within the allowable IOPS range for the selected volume size.
replicationFactor number Optional

Use replicationSpecs

replicationFactor is deprecated. Use replicationSpecs.

Number of replica set members. Each member keeps a copy of your databases, providing high availability and data redundancy. The possible values are 3, 5, or 7. The default value is 3.

Do not specify this field when creating a multi-region cluster using the replicationSpec document.

If your cluster is a sharded cluster, each shard is a replica set with the specified replication factor.

For information on how the replication factor affects costs, see Number of Servers. For more information on MongoDB replica sets, see Replication in the MongoDB manual.

Atlas ignores this value if you pass the replicationSpec document.

replicationSpec document Optional

Use replicationSpecs

replicationSpec is deprecated. Use replicationSpecs.

Configuration of each region in a multi-region cluster. Each element in this document represents a region where Atlas deploys your cluster.

For single-region clusters, you can either specify the providerSettings.regionName and replicationFactor, or you can use the replicationSpec document to define a single region.

For multi-region clusters, omit the providerSettings.regionName field.

For Global Clusters, specify the replicationSpecs parameter rather than a replicationSpec parameter.

Important

You must order each element in this document by replicationSpec.<region>.priority descending.

Use the replicationSpecs parameter to modify a Global Cluster.

Note

You cannot specify both the replicationSpec and replicationSpecs parameters in the same request body.

replicationSpec
.<region>
document Optional

Physical location of the region. Replace <region> with the name of the region. Each <region> document describes the region’s priority in elections and the number and type of MongoDB nodes Atlas deploys to the region. You must order each <region> by replicationSpec.priority descending.

You must specify at least one replicationSpec.<region> document.

For each <region> document, you must specify the electableNodes, priority, and readOnlyNodes fields.

During deployment of an M10+ dedicated paid cluster, Atlas creates a VPC for the selected provider and region or regions if no existing VPC or VPC peering connection exists for that provider and region. Atlas assigns the VPC a Classless Inter-Domain Routing (CIDR) block.

For clusters deployed on AWS, if you want to create a VPC peering connection to an AWS VPC and require a specific CIDR block for a given region, you must create a VPC connection before deploying the cluster. See Set up VPC Peering Connection for for complete documentation on VPC peering connections.

Important

Multi-region clusters require one VPC peering connection for each region. MongoDB nodes can use only the peering connection that resides in the same region as the nodes to communicate with the peered VPC.

Select your cloud provider’s tab for example cluster region names:

  • US_EAST_1
  • US_WEST_2
  • EU_WEST_1

For a complete list of supported AWS regions, see Amazon Web Services (AWS).

  • CENTRAL_US
  • WESTERN_EUROPE
  • EASTERN_ASIA_PACIFIC

For a complete list of supported GCP regions, see Google Cloud Platform (GCP).

  • US_EAST_2
  • US_WEST
  • EUROPE_NORTH

For a complete list of supported Azure regions, see Microsoft Azure.

replicationSpec
.<region>
.analyticsNodes
integer Optional

The number of analytics nodes for Atlas to deploy to the region. Analytics nodes are useful for handling analytic data such as reporting queries from BI Connector for Atlas. Analytics nodes are read-only, and can never become the primary.

If you do not specify this option, no analytics nodes are deployed to the region.

replicationSpec
.<region>
.electableNodes
integer Optional

Number of electable nodes for Atlas to deploy to the region. Electable nodes can become the primary and can facilitate local reads.

The total number of electableNodes across all replicationSpec.<region> document must be 3, 5, or 7.

Specify 0 if you do not want any electable nodes in the region.

You cannot create electable nodes if the replicationSpec.<region>.priority is 0.

replicationSpec
.<region>
.priority
integer Optional

Election priority of the region. For regions with only replicationSpec.<region>.readOnlyNodes, set this value to 0.

For regions where replicationSpec.<region>.electableNodes is at least 1, each replicationSpec.<region> must have a priority of exactly one (1) less than the previous region. The first region must have a priority of 7. The lowest possible priority is 1.

The priority 7 region identifies the Preferred Region of the cluster. Atlas places the primary node in the Preferred Region. Priorities 1 through 7 are exclusive - no more than one region per cluster can be assigned a given priority.

For example, if you have three regions, their priorities would be 7, 6, and 5 respectively. If you added two more regions for supporting electable nodes, the priorities of those regions would be 4 and 3 respectively.

replicationSpec
.<region>
.readOnlyNodes
integer Optional

Number of read-only nodes for Atlas to deploy to the region. Read-only nodes can never become the primary, but can facilitate local-reads.

Specify 0 if you do not want any read-only nodes in the region.

replicationSpecs array of documents Conditional

Configuration for cluster regions.

When should you use replicationSpecs?

Condition Necessity Values
You are deploying Global Clusters. Required Each document in the array represents a zone where Atlas deploys your cluster’s nodes.
You are deploying non-Global replica sets and sharded clusters. Optional This array has one document representing where Atlas deploys your cluster’s nodes.

You must specify all parameters in replicationSpecs document array.

What parameters depend on replicationSpecs?

If you set replicationSpecs, you must:

  • Set clusterType
  • Set diskTypeGB
  • Not set replicationSpec
  • Not use clusters with local NVMe SSDs
  • Not use Azure clusters
replicationSpecs[n]
.id
string Conditional

Unique identifer of the replication document for a zone in a Global Cluster.

When is this value needed?
Condition Necessity
Existing zones included in a cluster modification request body. Required
Adding a new zone to an existing Global Cluster. Optional

Warning

Atlas deletes any existing zones in a Global Cluster that are not included in a cluster modification request.

replicationSpecs[n]
.numShards
integer Optional Number of shards to deploy in the specified zone. The default value is 1.
replicationSpecs[n]
.regionsConfig
document Optional

Physical location of the region. Each regionsConfig document describes the region’s priority in elections and the number and type of MongoDB nodes Atlas deploys to the region. You must order each regionsConfigs document by regionsConfig.priority, descending.

During deployment of an M10+ dedicated paid cluster, Atlas creates a VPC for the selected provider and region or regions if no existing VPC or VPC peering connection exists for that provider and region. Atlas assigns the VPC a Classless Inter-Domain Routing (CIDR) block.

For clusters deployed on AWS, if you want to create a VPC peering connection to an AWS VPC and require a specific CIDR block for a given region, you must create a VPC connection before deploying the cluster. See Set up VPC Peering Connection for for complete documentation on VPC peering connections.

Important

Multi-region clusters require one VPC peering connection for each region. MongoDB nodes can use only the peering connection that resides in the same region as the nodes to communicate with the peered VPC.

Select your cloud provider’s tab for example cluster region names:

  • US_EAST_1
  • US_WEST_2
  • EU_WEST_1

For a complete list of supported AWS regions, see Amazon Web Services (AWS).

  • CENTRAL_US
  • WESTERN_EUROPE
  • EASTERN_ASIA_PACIFIC

For a complete list of supported GCP regions, see Google Cloud Platform (GCP).

  • US_EAST_2
  • US_WEST
  • EUROPE_NORTH

For a complete list of supported Azure regions, see Microsoft Azure.

replicationSpecs[n]
.regionsConfig
.electableNodes
integer Optional Number of electable nodes for Atlas to deploy to the region. Electable nodes can become the primary and can facilitate local reads.
replicationSpecs[n]
.regionsConfig
.readOnlyNodes
integer Optional

Number of read-only nodes for Atlas to deploy to the region. Read-only nodes can never become the primary, but can facilitate local-reads.

Specify 0 if you do not want any read-only nodes in the region.

replicationSpecs[n]
.regionsConfig
.analyticsNodes
integer Optional

The number of analytics nodes for Atlas to deploy to the region. Analytics nodes are useful for handling analytic data such as reporting queries from BI Connector for Atlas. Analytics nodes are read-only, and can never become the primary.

If you do not specify this option, no analytics nodes are deployed to the region.

replicationSpecs[n]
.regionsConfig
.priority
integer Optional Election priority of the region. For regions with only read-only nodes, set this value to 0.
replicationSpecs[n]
.zoneName
string Optional Name for the zone in a Global Cluster.

Response Elements

Name Type Description
autoScaling document
Contains the diskGBEnabled field which specifies whether to
enable or disable disk auto-scaling.
autoScaling.diskGBEnabled boolean Specifies whether disk auto-scaling is enabled.
backupEnabled boolean If true, the cluster uses Atlas Continuous Backups for backing up cluster data.
biConnector document

Information on whether BI Connector for Atlas is enabled or disabled for the cluster.

BI Connector for Atlas is only available for M10+ clusters.

The biConnector document includes the following fields:

Field Description
enabled
true if BI Connector for Atlas is enabled.
false if BI Connector for Atlas is disabled.
readPreference
"primary" if BI Connector for Atlas reads from the primary.
"secondary" if BI Connector for Atlas reads from a secondary.
"analytics" if BI Connector for Atlas reads from an analytics node.
clusterType string

Specifies the type of the cluster:

Value Description
REPLICASET replica set
SHARDED sharded cluster
GEOSHARDED Global Cluster
diskSizeGB double

AWS / GCP Only The size in gigabytes of the server’s root volume. You can add capacity by increasing this number, up to a maximum possible value of 4096 (i.e., 4 TB).

Each instance size has its own default value. To view default values:

  1. Open the Atlas web interface.
  2. Click the button to add a new cluster.
  3. View the available default sizes.
  4. Close the window without saving changes.
encryptionAtRestProvider string

Encryption at Rest is enabled or disabled.

For complete documentation on Encryption-at-Rest restrictions, see Restrictions.

You must configure encryption at rest for the Atlas project before enabling it on any cluster in the project. For complete documentation on configuring Encryption at Rest, see Encryption at Rest via AWS KMS.

groupId string Unique identifier of the project the cluster belongs to.
id string Unique identifier of the cluster.
mongoDBVersion string Version of MongoDB the cluster runs, in <major version>.<minor version> format.
mongoDBMajorVersion string

Major version of MongoDB the cluster runs:

  • 3.4
  • 3.6
  • 4.0
mongoURI string

Base connection string for the cluster.

Atlas only displays this field after the cluster is operational, not while it builds the cluster.

mongoURIUpdated string

Lists when the connection string was last updated. The connection string changes, for example, if you change a replica set to a sharded cluster.

Atlas only displays this field after the cluster is operational, not while it builds the cluster.

mongoURIWithOptions string

connection string for connecting to the Atlas cluster. Includes the replicaSet, ssl, and authSource query parameters in the connection string with values appropriate for the cluster.

To review the connection string format, see the connection string format documentation. To add MongoDB users to a Atlas project, see Configure MongoDB Users.

Atlas only displays this field after the cluster is operational, not while it builds the cluster.

name string Name of the cluster as it appears in Atlas.
numShards integer

Specifies the number of shards for a sharded cluster.

If this is set to 1, the cluster is a replica set.

If this is set to 2 or higher, the cluster is a sharded cluster with the number of shards specified.

For details on how this setting affects costs, see Number of Servers.

The possible values are 1 through 12.

Note

Not present in the response body for Global Clusters.

paused boolean Flag that indicates whether the cluster is paused or not.
providerBackupEnabled boolean If true, the cluster uses Cloud Provider Snapshots for backups. If providerBackupEnabled and backupEnabled are false, the cluster does not use Atlas backups.
providerSettings document Configuration for the provisioned servers on which MongoDB runs. The available options are specific to the cloud service provider.
providerSettings
.providerName
string

Cloud service provider on which the servers are provisioned.

The possible values are:

  • AWS - Amazon AWS
  • GCP - Google Cloud Platform
  • AZURE - Microsoft Azure
  • TENANT - Indicates an M2 or M5 multi-tenant cluster. See providerSettings.backingProviderName for the cloud service provider on which the server hosting the cluster is provisioned.
providerSettings
.backingProviderName
string

Cloud service provider on which the multi-tenant server is provisioned. Only visible if providerSettings.providerName is TENANT.

The possible values are:

  • AWS - Amazon AWS
  • GCP - Google Cloud Platform
  • AZURE - Microsoft Azure
providerSettings
.regionName
string

Physical location of your MongoDB cluster. The region you choose can affect network latency for clients accessing your databases.

For a complete list of region name values, refer to the the cloud provider reference pages:

For multi-region clusters, see replicationSpec.<region>.

providerSettings
.instanceSizeName
string

Name of the instance size used for the Atlas cluster.

Atlas supports the following instance sizes. Atlas supports deploying M2 and M5 instances into a subset of available regions. The documentation for providersettings.regionName includes a list of these regions.

Instance sizes with _NVME appended (for example: M40_NVME) use locally attached NVMe storage for exceptional performance with the most IO-intensive workloads.

Instance Size Default Storage Default RAM
M2 2GB Shared
M5 5GB Shared
M10 10GB 2GB
M20 20GB 4GB
M30 40GB 8GB
M40 or R40 80GB 16GB
M40_NVME 380GB 15.25GB
M50 or R50 160GB 32GB
M50_NVME 760GB 30.5GB
M60 or R60 320GB 64GB
M60_NVME 1.6TB 61GB
R80 750GB 122GB
M80_NVME 1.6TB 122GB
M100 1TB 160GB
M140 1 1TB 192GB
M200 or R200 1.5TB 256GB
M200_NVME 3.1TB 244GB
M300 1 2TB 384GB
R400 3TB 488GB
M400_NVME 2 4TB 512GB

1 Only available if providerSettings.regionName is EU-WEST-3 (Paris).

2 Available only in the following regions:

  • US_EAST_1
  • US_EAST_2
  • US_WEST_2
  • EU_WEST_1
  • EU_CENTRAL_1
  • AP_NORTHEAST_1
Instance Size Default Storage Default RAM
M2 2GB Shared
M5 5GB Shared
M10 10GB 1.70GB
M20 20GB 3.75GB
M30 40GB 7.5GB
M40 80GB 15GB
M50 160GB 30GB
M60 320GB 60GB
M80 750GB 120GB
M200 1 1.5TB 240GB
M300 1 2.2TB 360GB

1 Not available if providerSettings.regionName is SOUTH_AMERICA_EAST_1 , EUROPE_WEST_3, NORTHEASTERN_ASIA_PACIFIC, or AUSTRALIA_SOUTHEAST_1

Instance Size Default Storage Default RAM
M2 2GB Shared
M5 5GB Shared
M10 32GB 2GB
M20 32GB 4GB
M30 32GB 8GB
M40 128GB 16GB
M50 128GB 32GB
M60 128GB 64GB
M80 256GB 128GB
M200 256GB 256GB

Important

M2 and M5 instance sizes are multi-tenant deployments. You must set providerSettings.providerName to TENANT and specify the cloud service provider in providerSettings.backingProviderName.

providerSettings
.diskIOPS
integer Maximum input/output operations per second (IOPS) the system can perform.
providerSettings
.diskTypeName
string

Azure Only The disk type of the server’s root volume.

The following table lists the possible values for this field, and their corresponding storage size.

diskTypeName Storage Size
P4 1 32GB
P6 64GB
P10 2 128GB
P20 512GB
P30 1024GB
P40 2048GB
P50 4095GB

1 Default for M20 and M30 Azure instances

2 Default for M40+ Azure instances

providerSettings
.encryptEBSVolume
boolean AWS only. If enabled, the Amazon EBS encryption feature encrypts the server’s root volume for both data at rest within the volume and for data moving between the volume and the instance.
replicationFactor number

Number of replica set members. Each member keeps a copy of your databases, providing high availability and data redundancy.

For multi-region clusters, add the total number of replicationSpec.<region>.electableNodes to calculate the replication factor of the cluster.

If your cluster is a sharded cluster, each shard is a replica set with the specified replication factor.

For information on how the replication factor affects costs, see Number of Servers. For more information on MongoDB replica sets, see Replication in the MongoDB manual.

The possible values are 3, 5, or 7.

replicationSpec document Configuration of each region in the cluster. Each element in this document represents a region where Atlas deploys your cluster.
replicationSpec
.<region>
document

Physical location of the region. The <region> string corresponds to a region where Atlas deploys your cluster.

Each <region> document describes the region’s priority in elections and the number and type of MongoDB nodes Atlas deploys to the region.

replicationSpec
.<region>
.electableNodes
integer Number of electable nodes in the region. Electable nodes can become the primary and can facilitate local reads.
replicationSpec
.<region>
.priority
integer

Election priority of the region. The highest possible priority is 7, which identifies the Preferred Region of the cluster. Atlas places the primary node in the Preferred Region. The lowest possible priority is 0, which identifies a read only region.

You can have any number of priority 0 read only regions. Priorities 1 through 7 are exclusive - no more than one region per cluster can be assigned a given priority.

replicationSpec
.<region>
.readOnlyNodes
integer Number of read-only nodes in the region. Read-only nodes can never become the primary, but can facilitate local-reads.
replicationSpec.<region>.analyticsNodes integer The number of analytics nodes in the region. Analytics nodes are useful for handling analytic data such as reporting queries from BI Connector for Atlas. Analytics nodes are read-only, and can never become the primary.
replicationSpecs array of documents Configuration for each zone in a Global Cluster. Each document in this array represents a zone where Atlas deploys nodes for your Global Cluster.
replicationSpecs[n]
.id
string Unique identifier of the replication document.
replicationSpecs[n]
.zoneName
string Name for the zone.
replicationSpecs[n]
.numShards
integer Number of shards to deploy in the specified zone.
replicationSpecs[n]
.regionsConfig
document Physical location of the region. Each regionsConfig document describes the region’s priority in elections and the number and type of MongoDB nodes Atlas deploys to the region.
srvAddress string Connection string for connecting to the Atlas cluster. The +srv modifier forces the connection to use TLS/SSL. See the mongoURI for additional options.
stateName string

Current state of the cluster. The possible states are:

  • IDLE
  • CREATING
  • UPDATING
  • DELETING
  • DELETED
  • REPAIRING

Example

Request

curl --user "{username}:{apiKey}" --digest \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --include \
  --request PATCH "https://cloud.mongodb.com/api/atlas/v1.0/groups/5356823b3794de37132bb7b/clusters/datastore2" \
  --data '
    {
      "diskSizeGB" : 320,
      "providerSettings" : {
        "providerName" : "AWS",
        "diskIOPS" : 2400,
        "encryptEBSVolume" : false,
        "instanceSizeName" : "M40",
        "regionName" : "EU_WEST_1"
      },
      "replicationFactor" : 3,
      "encryptionAtRestProvider" : "AWS"
    }'
curl --user "{username}:{apiKey}" --digest \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --include \
  --request POST "https://cloud.mongodb.com/api/atlas/v1.0/groups/5356823b3794de37132bb7b/clusters" \
  --data '
    {
      "providerSettings" : {
        "providerName" : "AWS",
        "diskIOPS" : 480,
        "instanceSizeName" : "M10"
      },
      "replicationSpec": {
          "US_EAST_1": {
            "electableNodes": 3,
            "priority": 7,
            "readOnlyNodes" : 0
          },
          "US_EAST_2": {
            "electableNodes": 0,
            "priority" : 6,
            "readOnlyNodes" : 2
          },
          "US_WEST_1": {
            "electableNodes" : 0,
            "priority" : 5,
            "readOnlyNodes": 2
          }
       }
       "encryptionAtRestProvider" : "AWS"
    }'
curl --user "{username}:{apiKey}" --digest \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --include \
  --request PATCH "https://cloud.mongodb.com/api/atlas/v1.0/groups/6c392af480eef519ea5deeb1/clusters/GlobalCluster1?pretty=true" \
  --data '
    {
      "replicationSpecs": [
      {
        "id" : "5b4ccad387d9d64d6e43f881",
        "regionsConfig" : {
          "EU_CENTRAL_1" : {
            "electableNodes" : 3,
            "priority" : 7,
            "readOnlyNodes" : 0
          }
        },
        "zoneName" : "Zone 1"
      }]
    }'

Response

{
  "name" : "datastore2",
  "backupEnabled" : true,
  "biConnector": {
    "enabled": false,
    "readPreference": "secondary"
  },
  "clusterType": "REPLICASET",
  "diskSizeGB" : 320,
  "encryptionAtRestProvider" : "AWS",
  "groupId" : "5356823b3794de37132bb7b",
  "id": "59ef6621c0c6e378559875ed",
  "mongoDBVersion" : "3.6.8",
  "mongoURI" : "mongodb://mongo-shard-00-00.mongodb.net:27017,mongo-shard-00-01.mongodb.net:27017,mongo-shard-00-02.mongodb.net:27017",
  "mongoURIUpdated" : "2017-10-23T21:26:17Z",
  "mongoURIWithOptions" : "mongodb://mongo-shard-00-00.mongodb.net:27017,mongo-shard-00-01.mongodb.net:27017,mongo-shard-00-02.mongodb.net:27017/?ssl=true&authSource=admin&replicaSet=mongo-shard-0",
  "numShards" : 1,
  "paused" : false,
  "providerSettings" : {
    "providerName" : "AWS",
    "diskIOPS" : 2400,
    "encryptEBSVolume" : false,
    "instanceSizeName" : "M40",
    "regionName" : "EU_WEST_1"
  },
  "providerBackupEnabled" : "false",
  "replicationFactor" : 3,
  "srvAddress" : "mongodb+srv://mongo-shard-00-00.mongodb.net:27017,mongo-shard-00-01.mongodb.net:27017,mongo-shard-00-02.mongodb.net:27017",
  "stateName" : "UPDATING"
}
{
   "name" : "datastore2",
   "backupEnabled": false,
   "biConnector": {
     "enabled": false,
     "readPreference": "secondary"
   },
   "clusterType": "REPLICASET",
   "diskSizeGB": 160.0,
   "encryptionAtRestProvider" : "AWS",
   "groupId": "5356823b3794de37132bb7b",
   "id": "59ef6621c0c6e378559875ed",
   "links": [{
      "href": "https://cloud.mongodb.com/api/atlas/v1.0/groups/5356823b3794de37132bb7b/clusters/DataStore2",
      "rel": "self"
   }],
   "mongoDBMajorVersion": "3.4",
   "mongoDBVersion": "3.4.9",
   "mongoURI" : "mongodb://mongo-shard-00-00.mongodb.net:27017,mongo-shard-00-01.mongodb.net:27017,mongo-shard-00-02.mongodb.net:27017",
   "mongoURIUpdated" : "2017-10-23T21:26:17Z",
   "mongoURIWithOptions" : "mongodb://mongo-shard-00-00.mongodb.net:27017,mongo-shard-00-01.mongodb.net:27017,mongo-shard-00-02.mongodb.net:27017/?ssl=true&authSource=admin&replicaSet=mongo-shard-0",
   "name": "DataStore2",
   "numShards": 1,
   "paused" : false,
   "providerSettings": {
      "providerName": "AWS",
      "diskIOPS": 480,
      "encryptEBSVolume": true,
      "instanceSizeName": "M10"
   },
   "providerBackupEnabled" : "false",
   "replicationSpec": {
      "US_EAST_1": {
         "electableNodes": 3,
         "priority": 7,
         "readOnlyNodes": 0
      },
      "US_EAST_2": {
         "electableNodes": 2,
         "priority": 6,
         "readOnlyNodes": 0
      },
      "US_WEST_1": {
         "electableNodes": 2,
         "priority": 5,
         "readOnlyNodes": 2
      }
   },
   "srvAddress" : "mongodb+srv://mongo-shard-00-00.mongodb.net:27017,mongo-shard-00-01.mongodb.net:27017,mongo-shard-00-02.mongodb.net:27017",
   "stateName": "UPDATING"
}
{
  "autoScaling" : {
  "diskGBEnabled" : true
  },
  "backupEnabled" : false,
  "biConnector" : {
    "enabled" : false,
    "readPreference" : "secondary"
  },
  "clusterType" : "GEOSHARDED",
  "diskSizeGB" : 40.0,
  "encryptionAtRestProvider" : "NONE",
  "groupId" : "6c392af480eef519ea5deeb1",
  "id" : "5b4ccb5587d9d64d6e440d04",
  "links" : [ {
    "href" : "https://cloud.mongodb.com/api/atlas/v1.0/groups/6c392af480eef519ea5deeb1/clusters/GlobalCluster1",
    "rel" : "self"
  }, {
    "href" : "https://cloud.mongodb.com/api/atlas/v1.0/groups/6c392af480eef519ea5deeb1/clusters/GlobalCluster1/restoreJobs",
    "rel" : "http://mms.mongodb.com/restoreJobs"
  }, {
    "href" : "https://cloud.mongodb.com/api/atlas/v1.0/groups/6c392af480eef519ea5deeb1/clusters/GlobalCluster1/snapshots",
    "rel" : "http://mms.mongodb.com/snapshots"
  } ],
  "mongoDBMajorVersion" : "3.6",
  "mongoDBVersion" : "3.6.6",
  "mongoURI" : "mongodb://globalcluster1-shard-00-00-mlrwc.mongodb.net:27016,globalcluster1-shard-00-01-mlrwc.mongodb.net:27016,globalcluster1-shard-00-02-mlrwc.mongodb.net:27016,globalcluster1-shard-01-00-mlrwc.mongodb.net:27016,globalcluster1-shard-01-01-mlrwc.mongodb.net:27016,globalcluster1-shard-01-02-mlrwc.mongodb.net:27016",
  "mongoURIUpdated" : "2018-07-16T17:06:18Z",
  "mongoURIWithOptions" : "mongodb://globalcluster1-shard-00-00-mlrwc.mongodb.net:27016,globalcluster1-shard-00-01-mlrwc.mongodb.net:27016,globalcluster1-shard-00-02-mlrwc.mongodb.net:27016,globalcluster1-shard-01-00-mlrwc.mongodb.net:27016,globalcluster1-shard-01-01-mlrwc.mongodb.net:27016,globalcluster1-shard-01-02-mlrwc.mongodb.net:27016/?ssl=true&authSource=admin&replicaSet=GlobalCluster1-shard-0",
  "name" : "GlobalCluster1",
  "paused" : false,
  "providerBackupEnabled" : false,
  "providerSettings" : {
    "providerName" : "AWS",
    "diskIOPS" : 120,
    "encryptEBSVolume" : true,
    "instanceSizeName" : "M30"
  },
  "replicationSpecs" : [ {
    "id" : "5b4ccad387d9d64d6e43f881",
    "numShards" : 1,
    "regionsConfig" : {
      "EU_CENTRAL_1" : {
        "electableNodes" : 3,
        "priority" : 7,
        "readOnlyNodes" : 0
      }
    },
    "zoneName" : "Zone 1"
  } ],
  "srvAddress" : "mongodb+srv://globalcluster1-shard-00-00-mlrwc.mongodb.net:27016,globalcluster1-shard-00-01-mlrwc.mongodb.net:27016,globalcluster1-shard-00-02-mlrwc.mongodb.net:27016,globalcluster1-shard-01-00-mlrwc.mongodb.net:27016,globalcluster1-shard-01-01-mlrwc.mongodb.net:27016,globalcluster1-shard-01-02-mlrwc.mongodb.net:27016",
  "stateName" : "UPDATING"
}