Navigation

Create a Cluster

On this page

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), 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 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

POST /api/atlas/v1.0/groups/{GROUP-ID}/clusters

Request Path Parameters

Path Element Required/Optional Description
GROUP-ID Required. The unique identifier for the group in which to create the cluster.

Request Body Parameters

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

The version of the cluster to deploy. Atlas supports the following MongoDB versions:

  • 3.2
  • 3.4

Atlas always deploys the cluster with the latest stable release of the specified version.
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 12.

The default value is 1.
replicationFactor number

Optional

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.

The default value is 3.
providerSettings object 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
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.

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
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.
providerSettings.diskIOPS integer

Optional

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

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

Optional

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.

The default value is false.
diskSizeGB double

Optional

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

curl -u "username:apiKey" --digest -H "Content-Type: application/json" -X POST "https://cloud.mongodb.com/api/atlas/v1.0/groups/5356823b3794de37132bb7b/clusters" --data '
{
  "name" : "DataStore2",
  "diskSizeGB" : 160,
  "numShards" : 1,
  "providerSettings" : {
    "providerName" : "AWS",
    "diskIOPS" : 480,
    "encryptEBSVolume" : false,
    "instanceSizeName" : "M40",
    "regionName" : "US_EAST_1"
  },
  "replicationFactor" : 3,
  "backupEnabled" : true
}'

Response

{
   "backupEnabled" : true,
   "diskSizeGB" : 160,
   "groupId" : "5356823b3794de37132bb7b",
   "links" : [
      {
         "href" : "https://cloud.mongodb.com/api/atlas/v1.0/groups/5356823b3794de37132bb7b/clusters/DataStore2",
         "rel" : "self"
      }
   ],
   "mongoDBMajorVersion" : "3.4",
   "mongoDBVersion" : "3.4.3",
   "mongoURIUpdated" : "2017-04-14T15:02:33Z",
   "name" : "DataStore2",
   "numShards" : 1,
   "providerSettings" : {
      "providerName" : "AWS",
      "diskIOPS" : 480,
      "encryptEBSVolume" : false,
      "instanceSizeName" : "M40",
      "regionName" : "US_EAST_1"
   },
   "replicationFactor" : 3,
   "stateName" : "CREATING"
}

© MongoDB, Inc 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.