Modify a Cluster¶

Collection of settings that configures auto-scaling information for the cluster.

If you specify the autoScaling object, you must also specify the providerSettings.autoScaling object.

Specifies whether the cluster automatically scales its cluster tier and whether the cluster can scale down.

Flag that indicates whether cluster tier auto-scaling is enabled. The default is false.

• Set to true to enable cluster tier auto-scaling. If enabled, you must specify a value for providerSettings.autoScaling.compute.maxInstanceSize.
• Set to false to disable cluster tier auto-scaling.

Flag that indicates whether the cluster tier may scale down. Atlas requires this parameter if "autoScaling.compute.enabled" : true.

If you enable this option, specify a value for providerSettings.autoScaling.compute.minInstanceSize.

Flag that indicates 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.

The maximum amount of RAM for the selected cluster tier and the oplog size can limit storage auto-scaling. To learn more, see Customize Your Storage.

Flag that indicates whether legacy backups have been enabled.

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

You cannot enable legacy backups if you have an existing cluster in the project with Cloud Backups enabled.

The default value is false.

Configuration of BI Connector for Atlas on this cluster.

The MongoDB Connector for Business Intelligence for Atlas (BI Connector) is only available for M10 and larger clusters.

The BI Connector is a powerful tool which provides users SQL-based access to their MongoDB databases. As a result, the BI Connector performs operations which may be CPU and memory intensive. Given the limited hardware resources on M10 and M20 cluster tiers, you may experience performance degradation of the cluster when enabling the BI Connector. If this occurs, upgrade to an M30 or larger cluster or disable the BI Connector.

Flag that indicates 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.

Source from which the BI Connector for Atlas reads data. Each BI Connector for Atlas read preference contains a distinct combination of readPreference and readPreferenceTags options.

Type of the cluster that you want to modify.

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

Atlas accepts:

Capacity, in gigabytes, of the host's root volume. Increase this number to add capacity, up to a maximum possible value of 4096 (4 TB). This value must be a positive integer.

The minimum disk size for dedicated clusters is 10 GB for AWS and Google Cloud, and 32 GB for Azure. If you specify diskSizeGB with a lower disk size, Atlas defaults to the minimum disk size value.

Each cluster tier has its own default value. If you set a value below the cluster 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.

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

Cloud service provider that offers Encryption at Rest.

Collection of key-value pairs that tag and categorize the cluster.

Each key and value has a maximum length of 255 characters.

"labels": [
   {
     "key": "example key",
     "value": "example value"
   }
 ]

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

• 4.0
• 4.2
• 4.4
• 5.0

You must deploy MongoDB 4.4 if "providerSettings.instanceSizeName" : "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

If mongoDBMajorVersion is set to CONTINUOUS, you must omit the mongoDBMajorVersion field. You can't modify the MongoDB version that you clusters run when you choose the continuous release cadence.

Positive integer that specifies the number of shards to deploy for a sharded cluster.

Atlas accepts 1 through 50, inclusive. The default value is 1.

• If you specify a numShards value of 1 and a clusterType of SHARDED, Atlas deploys a single-shard sharded cluster.
• If you specify a numShards value of 1 and a clusterType of REPLICASET, Atlas deploys a replica set.

Don't create a sharded cluster with a single shard for production environments. Single-shard sharded clusters don't provide the same benefits as multi-shard configurations.

For more information on sharded clusters, see Sharding in the MongoDB manual.

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

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

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

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

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

You cannot enable Cloud Backups if you have an existing cluster in the project with Legacy Backups enabled.

Contains the minInstanceSize and maxInstanceSize parameters which specify the range of instance sizes to which your cluster can scale. Atlas requires this parameter if "autoScaling.compute.enabled" : true.

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

This setting only works when "providerSetting.providerName" : "TENANT" and "providerSetting.instanceSizeName" : M2 or M5.

Atlas accepts the following values:

Disk IOPS setting for AWS storage. Set only if you selected AWS as your cloud service provider.

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

This setting requires that providerSettings.instanceSizeName to be M30 or greater and cannot be used with clusters with local NVMe SSDs.

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

1. Open the Atlas web console.
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 cluster tier 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.

Click Provision IOPS to see the available IOPS range.

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 cluster tier's Standard IOPS value, as viewable in the Atlas console.

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

Atlas enforces the following minimum ratios for given cluster tiers. This keeps cluster performance consistent with large datasets.

Instance sizes M10 to M40 have a ratio of disk capacity to system memory of 60:1. Instance sizes greater than M40 have a ratio of 120:1.

Type of disk if you selected Azure as your cloud service provider.

Disk type of the server's root volume for Azure instances. If omitted, Atlas uses the default disk type for the selected providerSettings.instanceSizeName.

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

¹ Default for M10 Azure clusters

² Default for M20 Azure clusters

³ Default for M30 Azure clusters

⁴ Default for M40+ Azure clusters

Flag that indicates whether the Amazon EBS encryption feature encrypts the host's root volume for both data at rest within the volume and for data moving between the volume and the cluster.

The default value is true.

Atlas provides different cluster tiers, each with a default storage capacity and RAM size. The cluster you select is used for all the data-bearing servers in your cluster.

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

Cloud service provider on which Atlas provisions the hosts.

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

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

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

When Atlas deploys a dedicated cluster, Atlas checks if a VPC or VPC connection exists for that provider and region. If not, Atlas creates them as part of the deployment. Atlas assigns the VPC a CIDR block.

To limit a new VPC peering connection to one CIDR block and region, create the connection first. Deploy the cluster after the connection starts.

Google Cloud Clusters

Google Cloud Atlas clusters use a default CIDR block of /18. If your application requires a smaller block, create a network peering container first. Atlas limits the clusters you create to the regions in this new container you created.

Multi-Region Clusters

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.

To learn more, see Set up a Network Peering Connection.

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

Disk IOPS setting for AWS storage. Set only if you selected AWS as your cloud service provider.

The API resource accepts STANDARD, the default, and PROVISIONED.

• STANDARD volume types can't exceed the default IOPS rate for the selected volume size.
• PROVISIONED volume types must fall within the allowable IOPS range for the selected volume size.

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

Don't specify this parameter when creating a multi-region cluster using the replicationSpec object.

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

Atlas ignores this value if you pass the replicationSpec object.

Configuration of each region in a multi-region cluster. Each element in this object 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 object to define a single region.

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

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

Use the replicationSpecs parameter to modify a Global Cluster.

Physical location of the region. Replace <region> with the name of the region. Each <region> object describes the region's priority in elections and the number and type of MongoDB nodes Atlas deploys to the region.

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

For each <region> object, you must specify the analyticsNodes, electableNodes, priority, and readOnlyNodes parameters.

When Atlas deploys a dedicated cluster, Atlas checks if a VPC or VPC connection exists for that provider and region. If not, Atlas creates them as part of the deployment. Atlas assigns the VPC a CIDR block.

To limit a new VPC peering connection to one CIDR block and region, create the connection first. Deploy the cluster after the connection starts.

Google Cloud Clusters

Google Cloud Atlas clusters use a default CIDR block of /18. If your application requires a smaller block, create a network peering container first. Atlas limits the clusters you create to the regions in this new container you created.

Multi-Region Clusters

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.

To learn more, see Set up a Network Peering Connection.

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.

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> object 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.

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: you can't assign a given priority to more than one region per cluster.

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.

Configuration for cluster regions.

You must specify all parameters in replicationSpecs object array.

Unique identifier of the replication object for a zone in a Global Cluster. Must be exactly 24 hexadecimal digits in length.

Configuration for a region. Each regionsConfig object describes the region's priority in elections and the number and type of MongoDB nodes that Atlas deploys to the region.

Physical location of the region. Replace <region> with the name of the region. Each <region> object describes the region's priority in elections and the number and type of MongoDB nodes Atlas deploys to the region.

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

For each <region> object, you must specify the analyticsNodes, electableNodes, priority, and readOnlyNodes parameters.

When Atlas deploys a dedicated cluster, Atlas checks if a VPC or VPC connection exists for that provider and region. If not, Atlas creates them as part of the deployment. Atlas assigns the VPC a CIDR block.

To limit a new VPC peering connection to one CIDR block and region, create the connection first. Deploy the cluster after the connection starts.

Google Cloud Clusters

Google Cloud Atlas clusters use a default CIDR block of /18. If your application requires a smaller block, create a network peering container first. Atlas limits the clusters you create to the regions in this new container you created.

Multi-Region Clusters

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.

To learn more, see Set up a Network Peering Connection.

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.

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 replicationSpecs[n].regionsConfig.<region> object 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 replicationSpecs[n].regionsConfig.<region>.priority is 0.

Election priority of the region. For regions with only replicationSpecs[n].regionsConfig.<region>.readOnlyNodes, set this value to 0.

For regions where replicationSpecs[n].regionsConfig.<region>.electableNodes is at least 1, each replicationSpecs[n].regionsConfig.<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: you can't assign a given priority to more than one region per cluster.

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.

Certificate Authority that MongoDB Atlas clusters use. You can specify ISRGROOTX1 (for ISRG Root X1).

Release cadence that Atlas uses for this cluster. Atlas accepts:

• CONTINUOUS: Atlas automatically updates your cluster to the latest major and rapid MongoDB releases as they become available.
• LTS: Atlas automatically updates your cluster to subsequent patch releases of this MongoDB version. Atlas doesn't update your cluster to newer rapid or major MongoDB releases as they become available.

If you set this field to CONTINUOUS, you must omit the mongoDBMajorVersion field.

You can change from LTS to CONTINUOUS only if your cluster runs the most recent MongoDB major release.

You can change from CONTINUOUS to LTS only if the most recent MongoDB release is a major version. For example, if the most recent MongoDB release is 5.0, you can switch from CONTINUOUS to LTS. If the most recent MongoDB release is 5.1, you must wait until MongoDB 6.0 is released to switch from CONTINUOUS to LTS.