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. This page uses the more familiar term group. The endpoints are as stated on the page.

Note

This feature is not available for M0 (Free Tier) clusters. For more information, see Atlas M0 (Free Tier) Limitations.

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

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

Base URL: https://cloud.mongodb.com/

Syntax

PATCH /api/atlas/v1.0/groups/{GROUP-ID}/clusters/{CLUSTER-NAME}

Request Path Parameters

Path Element Required/Optional Description
GROUP-ID Required. The unique identifier for the group containing the cluster.
CLUSTER-NAME Required The 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.

Name Type Description
autoScaling document

Optional

Specify whether to enable/disable disk auto-scaling. The document contains diskGBEnabled field:

  • Set to true to enable disk auto-scaling.
  • Set to false to disabled disk auto-scaling.
mongoDBMajorVersion string

For a cluster running with MongoDB 3.2, specify 3.4 to direct Atlas to upgrade the cluster to MongoDB 3.4.

For a cluster running with MongoDB 3.4, specify 3.6 to direct Atlas to upgrade the cluster to MongoDB 3.6.

You cannot modify this field for M2 or M5 shared tier clusters.

Atlas always upgrades the cluster to the latest stable release of the specified version via a rolling process to maintain cluster availability.

You cannot downgrade the cluster to an earlier MongoDB version.

numShards integer

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

paused boolean

Optional A flag to pause or resume the cluster. Possible values are:

  • true to pause the cluster. You cannot pause a cluster with pending changes.
  • false to resume the cluster. Default.

Note

Available for M10+ Clusters.

You cannot pause a cluster with pending changes. If the cluster is paused for 7 days, Atlas auto-resumes the cluster.

providerSettings document The configuration for the provisioned servers on which MongoDB runs. The available options are specific to the cloud service provider.
providerSettings.providerName string

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

You must include this value if modifying any of the other providerSettings.

providerSettings.backingProviderName string

The cloud service provider on which the server for a multi-tenant cluster is provisioned. This setting is only valid when providerSettings.providerName is TENANT and providerSettings.instanceSizeName is M2 or M5.

The possible values are:

  • AWS - Amazon AWS
  • GCP - Google Cloud Platform
  • AZURE - Microsoft Azure

You must include this value if modifying any of the other providerSettings.

providerSettings.regionName string

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

Atlas ignores this value if you specify 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

AWS does not support cross-region VPC peering. Multi-region clusters require one VPC peering connection per region. Only those MongoDB nodes in that region can use the peering connection to communicate with the peered VPC.

The following regions are valid for M10+ clusters.

AWS GCP AZURE
  • US_EAST_1
  • US_EAST_2
  • US_WEST_1
  • US_WEST_2
  • CA_CENTRAL_1
  • EU_WEST_1
  • EU_WEST_2
  • EU_CENTRAL_1
  • AP_NORTHEAST_1
  • AP_NORTHEAST_2
  • AP_SOUTHEAST_1
  • AP_SOUTHEAST_2
  • AP_SOUTH_1
  • SA_EAST_1

Note

EASTERN_US corresponds to the GCP us_east_1 region.

  • CENTRAL_US
  • EASTERN_US
  • WESTERN_EUROPE
  • EASTERN_ASIA_PACIFIC
  • US_CENTRAL
  • US_EAST
  • US_EAST_2
  • US_NORTH_CENTRAL
  • US_WEST
  • US_SOUTH_CENTRAL
  • EUROPE_NORTH
  • EUROPE_WEST

The following regions are valid for M2 and M5 clusters:

AWS GCP AZURE
  • US_EAST_1
  • US_WEST_2
  • EU_WEST_1
  • AP_SOUTHEAST_2

Note

EASTERN_US corresponds to the GCP us_east_1 region.

  • CENTRAL_US
  • WESTERN_EUROPE
  • EASTERN_ASIA_PACIFIC
  • US_EAST_2
  • EUROPE_NORTH

You must include providerSettings.providerName if modifying this value.

providerSettings.instanceSizeName string

Atlas provides different instance sizes, each with a default RAM size, storage capacity, and maximum storage speed. 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.

You can customize the instance size using the diskSizeGB and providerSettings.diskIOPS fields. Doing so affects costs, as described in Billing.

In the API, enter the instance size exactly as it is named in the interface. For example, for M40 enter M40.

To view available instance sizes: open the Atlas web interface; select Build a New Cluster; select your preferred cloud service provider and region; view the available instance sizes; close the window without saving changes.

You must include providerSettings.providerName if modifying this value.

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

The maximum input/output operations per second (IOPS) the system can perform. The available IOPS depend on the instance size: each instance size has a specific set of available IOPS values. To view available values: open the Atlas web interface; select Build a New Cluster; select your preferred cloud service provider and region; click an instance size to view the available values; close the window without saving changes.

You must include providerSettings.providerName if modifying this value.

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.

You must include providerSettings.providerName if modifying this value.

replicationFactor number

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

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.

Atlas ignores this value if you specify the replicationSpec document.

replicationSpec document

Optional

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

If you specify replicationSpec, Atlas overrides any values you specify to the providerSettings.regionName or replicationFactor field with values derived from replicationSpec.

Important

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

replicationSpec.<region> document

Required if specifying replicationSpec

The 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 specify at least one replicationSpec.<region> 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

AWS does not support cross-region VPC peering. Multi-region clusters require one VPC peering connection per region. Only those MongoDB nodes in that region can use the peering connection to communicate with the peered VPC.

AWS GCP AZURE
  • US_EAST_1
  • US_EAST_2
  • US_WEST_1
  • US_WEST_2
  • CA_CENTRAL_1
  • EU_WEST_1
  • EU_WEST_2
  • EU_CENTRAL_1
  • AP_NORTHEAST_1
  • AP_NORTHEAST_2
  • AP_SOUTHEAST_1
  • AP_SOUTHEAST_2
  • AP_SOUTH_1
  • SA_EAST_1

Note

EASTERN_US corresponds to the GCP us_east_1 region.

  • CENTRAL_US
  • EASTERN_US
  • WESTERN_EUROPE
  • EASTERN_ASIA_PACIFIC
  • US_CENTRAL
  • US_EAST
  • US_EAST_2
  • US_NORTH_CENTRAL
  • US_WEST
  • US_SOUTH_CENTRAL
  • EUROPE_NORTH
  • EUROPE_WEST

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

replicationSpec.<region>.electableNodes integer

Required

The 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> documents 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

Required

The 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

Required

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

diskSizeGB double

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 16384 (i.e., 16 TB).

Important

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

backupEnabled Boolean If enabled, the Atlas Backup service takes snapshots of your databases at regular intervals and retains them according to your group’s retention policy.

HTTP Response Elements

Name Type Description
autoScaling document

Information on whether disk auto-scaling is enabled. The document contains diskGBEnabled field set to:

  • true if enabled.
  • false if disabled.

Default is true.

name string The name of the cluster as it appears in Atlas.
groupId string ID of the group the cluster belongs to.
id string ID of the cluster.
mongoDBVersion string The version of MongoDB the cluster runs, in <major version>.<minor version> format.
mongoDBMajorVersion string

The major version of MongoDB the cluster runs. Atlas supports the following MongoDB versions:

  • 3.2
  • 3.4
  • 3.6
mongoURI string

The connection string for connecting to the cluster through a MongoDB driver or the mongo shell. To download the mongo shell, click a cluster’s Connect button and follow the download instructions.

When you create a new cluster, the mongoURI will not show up while the cluster is being built. Atlas provides the connection string only after the cluster is running.

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.
numShards integer

Selects whether the cluster is a sharded cluster or a replica set and specifies the number of shards for 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 12.

paused boolean A flag that indicates whether the cluster is paused or not.
providerSettings document The configuration for the provisioned servers on which MongoDB runs. The available options are specific to the cloud service provider.
providerSettings.providerName string

The 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

The 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

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

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

AWS does not support cross-region VPC peering. Multi-region clusters require one VPC peering connection per region. Only those MongoDB nodes in that region can use the peering connection to communicate with the peered VPC.

Provider Regions
AWS
  • US_EAST_1
  • US_EAST_2
  • US_WEST_1
  • US_WEST_2
  • CA_CENTRAL_1
  • EU_WEST_1
  • EU_WEST_2
  • EU_CENTRAL_1
  • AP_NORTHEAST_1
  • AP_NORTHEAST_2
  • AP_SOUTHEAST_1
  • AP_SOUTHEAST_2
  • AP_SOUTH_1
  • SA_EAST_1
GCP

Note

EASTERN_US corresponds to the GCP us_east_1 region.

  • CENTRAL_US
  • EASTERN_US
  • WESTERN_EUROPE
  • EASTERN_ASIA_PACIFIC
Azure
  • US_CENTRAL
  • US_EAST
  • US_EAST_2
  • US_NORTH_CENTRAL
  • US_WEST
  • US_SOUTH_CENTRAL
  • EUROPE_NORTH
  • EUROPE_WEST
providerSettings.instanceSizeName string

The name of the instance size used for the Atlas cluster.

To view available instance sizes: open the Atlas web interface; select Build a New Cluster; select your preferred cloud service provider and region; view the available instance sizes; close the window without saving changes.

providerSettings.diskIOPS integer The maximum input/output operations per second (IOPS) the system can perform. The available IOPS depend on the instance size: each instance size has a specific set of available IOPS values. To view available values: open the Atlas web interface; select Build a New Cluster; select your preferred cloud service provider and region; click an instance size to view the available values for Custom Storage Speed; close the window without saving changes.
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

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

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 The configuration of each region in the cluster. Each element in this document represents a region where Atlas deploys your cluster.
replicationSpec.<region> document

The 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 The number of electable nodes in the region. Electable nodes can become the primary and can facilitate local reads.
replicationSpec.<region>.priority integer

The 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 The number of read-only nodes in the region. Read-only nodes can never become the primary, but can facilitate local-reads.
diskSizeGB double

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 16384 (i.e., 16 TB).

Each instance size has its own 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.

backupEnabled Boolean If enabled, the Atlas Backup service takes snapshots of your databases at regular intervals and retains them according to your group’s retention policy.
stateName string

The current state of the cluster. The possible states are:

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

Example

Request

Single Region Modification Request

curl -i -u "username:apiKey" --digest -H "Content-Type: application/json" -X 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
}'

Multi Region Modification Request

curl -i -u "username:apiKey" --digest -H "Content-Type: application/json" -X 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
      }
   }
}'

Response

Single Region Modification Response

HTTP/1.1 200 OK

{
  "name" : "datastore2",
  "backupEnabled" : true,
  "diskSizeGB" : 320,
  "groupId" : "5356823b3794de37132bb7b",
  "id": "59ef6621c0c6e378559875ed",
  "mongoDBVersion" : "3.2.8",
  "mongoURI" : "mongodb://datastore2-shard-00-00.example.net:27017,datastore2-shard-00-01.example.net:27017,datastore2-shard-00-02.example.net:27017",
  "mongoURIUpdated" : "2016-08-03T15:19:24Z",
  "numShards" : 1,
  "paused" : false,
  "providerSettings" : {
    "providerName" : "AWS",
    "diskIOPS" : 2400,
    "encryptEBSVolume" : false,
    "instanceSizeName" : "M40",
    "regionName" : "EU_WEST_1"
  },
  "replicationFactor" : 3,
  "stateName" : "UPDATING"
}

Multi Region Modification Response

{
   "name" : "datastore2",
   "backupEnabled": false,
   "diskSizeGB": 160.0,
   "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://datastore2-shard-00-00.example.net:27017,datastore2-shard-00-01.example.net:27017,datastore2-shard-00-02.example.net:27017",
   "mongoURIUpdated": "2017-10-24T16:11:13Z",
   "name": "DataStore2",
   "numShards": 1,
   "paused" : false,
   "providerSettings": {
      "providerName": "AWS",
      "diskIOPS": 480,
      "encryptEBSVolume": true,
      "instanceSizeName": "M10"
   },
   "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
      }
   },
   "stateName": "UPDATING"
}