Cluster Configuration File

On this page

Required Cluster Settings

Optional and Conditional Cluster Settings
Example Cluster Configuration File
Example Multi-Cloud Cluster Configuration File
Example Geosharded Cluster Configuration File

You can use a cluster configuration file to specify the settings required when you create or update a cluster using the Atlas CLI. The Atlas CLI accepts .json cluster configuration files.

Use the following resources to:

Learn the required settings you can specify in the cluster configuration file.
View and copy sample configuration files.

Required Cluster Settings

Atlas requires the following settings to create a cluster with the Atlas CLI. You must specify these cluster settings either in the configuration file or as flags in the command:

Field	Type	Description
`clusterType`	string	Human-readable label that indicates the type of cluster to create. Values include: `REPLICASET`, `SHARDED`, or `GEOSHARDED`.
`name`	string	Human-readable label that identifies the cluster.
`replicationSpecs`	array	List that contains the configuration settings for your cluster regions and the hardware provisioned in them.
`replicationSpecs.` `regionConfigs`	array	List that contains the hardware specifications for the nodes set within the region that you specify. Each `regionConfigs` object describes the region's priority in elections and the number and type of MongoDB nodes that Atlas deploys to the region. Each `regionConfigs` object must have either an `analyticsSpecs` object, `electableSpecs` object, or `readOnlySpecs` object. Shared clusters require only `electableSpecs`. Dedicated clusters can specify any of these specifications, but must have at least one `electableSpecs` object within a `replicationSpec`. Every hardware specification must use the same `instanceSize`.
`replicationSpecs.` `regionConfigs.electableSpecs`	object	Hardware specifications for electable nodes in the region. Electable nodes can become the primary and can enable local reads.
`replicationSpecs.` `regionConfigs.` `electableSpecs.instanceSize`	string	Hardware specification for the instance sizes in this region. To learn more, see Select Cluster Tier.
`replicationSpecs` `.regionConfigs.` `electableSpecs.nodeCount`	number	Number of electable nodes for Atlas to deploy to the region. Electable nodes can become the primary and can enable local reads. The combined electableSpecs.nodeCount across all replicationSpecs[n].regionConfigs[m] objects must total 3, 5, or 7.
`replicationSpecs.` `regionConfigs.priority`	Integer	Precedence that is given to this region when a primary election occurs. If your region has set `electableSpecs.nodeCount` to `1` or higher, it must have a priority of exactly one (1) less than another region in the `replicationSpecs[n].regionConfigs[m]` array. The highest-priority 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.
`replicationSpecs.` `regionConfigs.providerName`	string	Human-readable label that identifies your cloud service provider. Values include: `AWS`, `AZURE`, or `GCP`. To create a multi-cloud cluster, specify more than one service provider for your `regionConfigs` objects. To learn more, see the multi-cloud example configuration file
`replicationSpecs.` `regionConfigs.regionName`	string	Human-readable label that indicates the physical location of your cluster nodes. 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: AWS GCP Azure

Optional and Conditional Cluster Settings

Your cluster configuration file may contain additional optional or conditional cluster settings. If you selected a clusterType of GEOSHARDED, you must specify the following cluster settings either in the configuration file or as flags in the command:

Field	Type	Description
`replicationSpecs.` `numShards`	string	Positive integer that specifies the number of shards to deploy in each specified zone. Provide this value if you set a `clusterType` of `SHARDED` or `GEOSHARDED`. Omit this value if you selected a `clusterType` of `REPLICASET`. This API resource accepts `1` through `50`, inclusive. This parameter defaults to `1`. If you specify a `numShards` value of `1` and a `clusterType` of `SHARDED`, Atlas deploys a single-shard sharded cluster. 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.
`replicationSpecs.` `zoneName`	string	Name for the zone in a Global Cluster. Provide this value if you set `clusterType` to `GEOSHARDED`.
`tags`	array	List that contains key-value pairs between 1 to 255 characters in length for tagging and categorizing the cluster.
`tags.key`	string	Constant that defines the set of the tag. For example, `environment` in the `environment : production` tag.
`tags.value`	string	Variable that belongs to the set of the tag. For example, `production` in the `environment : production` tag.

For a full list of available settings, see the API documentation for Create One Multi-Cloud Cluster from One Project.

Example Cluster Configuration File

To create a cluster using a single cloud provider, specify the same service provider for your regionConfigs objects as shown in the following example file:

{
  "name":"myCluster",
  "clusterType":"REPLICASET",
  "replicationSpecs":[
    {
      "regionConfigs":[
        {
          "electableSpecs":{
            "instanceSize":"M30",
            "nodeCount":1
          },
          "priority":7,
          "providerName":"AWS",
          "regionName":"EU_WEST_1"
        },
        {
          "electableSpecs":{
            "instanceSize":"M30",
            "nodeCount":1
          },
          "priority":6,
          "providerName":"AWS",
          "regionName":"US_EAST_1"
        },
        {
          "electableSpecs":{
            "instanceSize":"M30",
            "nodeCount":1
          },
          "priority":5,
          "providerName":"AWS",
          "regionName":"US_WEST_1"
        }
      ]
    }
  ]
}

Example Multi-Cloud Cluster Configuration File

To create a multi-cloud cluster, specify more than one service provider for your regionConfigs objects as shown in the following example file:

{
  "name":"myCluster",
  "clusterType":"REPLICASET",
  "replicationSpecs":[
    {
      "regionConfigs":[
        {
          "electableSpecs":{
            "instanceSize":"M30",
            "nodeCount":1
          },
          "priority":7,
          "providerName":"AWS",
          "regionName":"EU_WEST_1"
        },
        {
          "electableSpecs":{
            "instanceSize":"M30",
            "nodeCount":1
          },
          "priority":6,
          "providerName":"GCP",
          "regionName":"CENTRAL_US"
        },
        {
          "electableSpecs":{
            "instanceSize":"M30",
            "nodeCount":1
          },
          "priority":5,
          "providerName":"AZURE",
          "regionName":"US_EAST_2"
        }
      ]
    }
  ]
}

Example Geosharded Cluster Configuration File

To create a geosharded cluster, specify zones for your replicationSpecs objects as shown in the following example file:

{
    "backupEnabled": false,
    "biConnector": {
      "enabled": false,
      "readPreference": "secondary"
    },
    "clusterType": "GEOSHARDED",
    "diskSizeGB": 100,
    "encryptionAtRestProvider": "NONE",
    "mongoDBMajorVersion": "5.0",
    "name": "myCluster",
    "paused": false,
    "pitEnabled": false,
    "stateName": "IDLE",
    "replicationSpecs": [
      {
        "numShards": 1,
        "zoneName": "US-1",
        "regionConfigs": [
          {
            "analyticsSpecs": {
              "diskIOPS": 3000,
              "ebsVolumeType": "STANDARD",
              "instanceSize": "M30",
              "nodeCount": 0
            },
            "electableSpecs": {
              "diskIOPS": 3000,
              "ebsVolumeType": "STANDARD",
              "instanceSize": "M30",
              "nodeCount": 3
            },
            "readOnlySpecs": {
              "diskIOPS": 3000,
              "ebsVolumeType": "STANDARD",
              "instanceSize": "M30",
              "nodeCount": 0
            },
            "autoScaling": {
              "diskGB": {
                "enabled": true
              },
              "compute": {
                "enabled": false,
                "scaleDownEnabled": false
              }
            },
            "priority": 7,
            "providerName": "AWS",
            "regionName": "US_EAST_1"
          }
        ]
      },
      {
        "numShards": 1,
        "zoneName": "US-2",
        "regionConfigs": [
          {
            "analyticsSpecs": {
              "diskIOPS": 3000,
              "ebsVolumeType": "STANDARD",
              "instanceSize": "M30",
              "nodeCount": 0
            },
            "electableSpecs": {
              "diskIOPS": 3000,
              "ebsVolumeType": "STANDARD",
              "instanceSize": "M30",
              "nodeCount": 3
            },
            "readOnlySpecs": {
              "diskIOPS": 3000,
              "ebsVolumeType": "STANDARD",
              "instanceSize": "M30",
              "nodeCount": 0
            },
            "autoScaling": {
              "diskGB": {
                "enabled": true
              },
              "compute": {
                "enabled": false,
                "scaleDownEnabled": false
              }
            },
            "priority": 7,
            "providerName": "AWS",
            "regionName": "US_EAST_2"
          }
        ]
      }
    ]
  }

Back

JSON Configuration Files

Cloud Backup Schedule