Navigation

Create a Global Cluster

This tutorial covers creating and configuring a new Atlas Global Cluster for using Global Writes.

Once deployed, you cannot convert a Global Cluster to a standard sharded cluster. Thoroughly familiarize yourself with the Global Clusters documentation before creating a Global Cluster.

Important

Atlas supports creating VPC peering connections between your Atlas dedicated paid clusters and other AWS VPCs in the same region.

If this is the first dedicated paid cluster for the selected region or regions and you plan on creating one or more VPC peering connections, please review the documentation on VPC Peering Connections before continuing.

A. Open the Create New Cluster Dialog

Note

Before creating a cluster, check that you have the correct organization and project selected. Click the Context drop down in the top left corner to select a specific organization or project. For more information on creating and managing organizations and projects, see Organizations and Projects.

Each Atlas project supports up to 50 clusters. Please contact Atlas support for questions or assistance regarding the cluster limit. To contact support, select Support from the left-hand navigation bar of the Atlas UI.

Go to the Clusters view and click the Add New Cluster or Build a New Cluster button to display the Create New Cluster dialog. As you build your cluster, Atlas displays the associated costs at the bottom of the screen. You can hover over the displayed cost for additional estimates.

B. Set up your Global Cluster Configuration.

Click Global Cluster Configuration to expand the section. Toggle Enable Global Writes (M30 and Up) to On to display the Global Cluster configuration.

Select your preferred cloud provider. Each cloud provider has a selection of global regions to which Atlas can deploy a zone. The choice of cloud provider may support or constrict your ability to deploy a zone to specific geographic locations. The configuration options available and the cost for running the cluster may also vary depending on cloud provider selection.

Once you select your cloud service provider, you must configure your Global Cluster zones.

C. Configure your Global Cluster Zones.

Configure Global Writes Zones Using a Template

Atlas provides two templates for configuring Global Writes zones for the cluster, each with a description of the purpose of its underlying configuration. Click on a template to view the Zone Map for that template. The Zone Map provides a visual description of the cluster zone configuration, including estimates of geographic latency and coverage.

Click Zone configuration summary below the zone map to view a summary of each zone in the Global Cluster. Atlas provides the the following validations for each zone:

Validation Guidance
Low latency reads and writes in <geography> Indicates the geographic locale for which the zone supports low latency reads and writes. The exact geographic locale specified depends on the preferred Region for that zone. You can modify the zone’s preferred region in the Zone Configuration section.
Local reads in all other zones

Indicates whether data in this zone is replicated to every other zone for local secondary reads by clients in those zones.

Click the Configure Local Reads in All Zones button in the Zone configuration summary to automatically configure every zone in the cluster for local reads.

(Not) Available during partial region outage

Indicates whether the zone supports high availability, such that a majority of electable nodes remain healthy and reachable in the event of a partial region outage. Regions marked as Recommended in the Atlas UI support high availability during partial regional outages.

For complete documentation on how Atlas ensures high availability in a single region, see

(Not) Available during full region outage Indicates whether the zone supports high availability, such that a majority of electable nodes remain healthy and rechable in the event of a complete regional outage.

By default each template deploys a series of single-region zones and builds a map of country and subdivision locations geographically near each zone. MongoDB uses this location-zone map to route read and write operations which contain location data to the shard or shards in the corresponding zone. For complete documentation on Global Cluster read and write operation routing, see Global Cluster Write Operations and Global Cluster Read Operations.

Click the Configure Location Mappings in the Zone Map to view the list of location-zone mappings. To customize the location-zone mapping, click the Zone dropdown for a given Location Name and select a new zone. Click the Reset button to reset a custom mapping for any given location. Click the Reset All Zone mappings button to reset all custom mappings for the cluster.

You can make additional configuration changes to each zone after selecting a zone template.

You can also create Multi-region zones. Clicking Configure Local Reads in All Zones converts all zones to multi-region.

Click View Zone Templates in the Zone Map to return to the template selection.

Configure a Global Writes Single Region Zone

The Zone Configuration section allows you to configure each zone in your cluster. Atlas displays a drop-down box directly above the Zone Configuration that indicates the currently selected zone. Click the + Add a Zone button to add additional zones to the Global Cluster, up to a maximum of nine (9) zones.

The Zone Map updates as you modify each zone. If the Zone Map currently displays the template selection menu, click Configure Zones Myself to view the Zone map.

Click the Select the preferred region for your zone drop-down box and select a region as the Preferred Region for each shard assigned to the zone. Atlas builds a map of countries and subdivisions geographically near the selected region. MongoDB uses this location-zone map to route read and write operations which contain location data to the shard or shards in the corresponding zone. For complete documentation on Global Cluster read and write operation routing, see Global Cluster Write Operations and Global Cluster Read Operations.

Click the Configure Location Mappings in the Zone Map to view the list of location-zone mappings. To customize the location-zone mapping, click the Zone dropdown for a given Location Name and select a new zone. Click the Reset button to reset a custom mapping for any given location. Click the Reset All Zone mappings button to reset all custom mappings for the cluster.

For each shard in the zone, Atlas distributes the shard nodes with respect to the Zone Configuration. You can add additional shards to the zone by clicking Additional Options in the Zone Configuration section and selecting the total number of shards in the zone from the drop-down box. By default Atlas deploys one shard per zone. Atlas recommends creating additional zones to support heavy write load in a geographic region instead of adding multiple shards to a single zone. Atlas supports no more than 24 shards per Global Cluster.

Important

Selecting a zone template resets any configuration changes made in the Zone Configuration section to the default for the selected template.

Configure a Global Writes Multi Region Zone

The Zone Configuration section allows you to configure each zone in your cluster. Atlas displays a drop-down box directly above the Zone Configuration that indicates the currently selected zone. Click the + Add a Zone button to add additional zones to the Global Cluster, up to a maximum of nine (9) zones.

The Zone Map updates as you modify each zone. If the Zone Map currently displays the template selection menu, click Configure Zones Myself to view the Zone map.

Click the Add secondary and read-only regions button to display the multi-region configuration controls. Zones for which you toggled the Configure Local Reads in All Zones in the Zone configuration summary display the multi-region zone controls by default.

Deploy across multiple regions

Configure the Preferred and Electable nodes in the zone. For more information on the Node Types, see Global Write Zones and Zone Mapping.

Each row represents one Region where Atlas deploys the configured Number of Nodes of the listed Node Type. Atlas builds a map of countries and subdivisions geographically near the selected region for the Preferred Node Type. MongoDB uses this location-zone map to route read and write operations which contain location data to the shard or shards in the corresponding zone. For complete documentation on Global Cluster read and write operation routing, see Global Cluster Write Operations and Global Cluster Read Operations.

Click the Configure Location Mappings in the Zone Map to view the list of location-zone mappings. To customize the location-zone mapping, click the Zone dropdown for a given Location Name and select a new zone. Click the Reset button to reset a custom mapping for any given location. Click the Reset All Zone mappings button to reset all custom mappings for the cluster.

Click Add a node to add additional Electable rows. The total number of Electable and Preferred nodes across all regions must be 3, 5, or 7. Consider distributing your nodes such that the loss of an entire region leaves a majority of healthy electable nodes available.

Deploy read-only-replicas

Configure the Read-only nodes in the zone. Each row represents one Region where Atlas deploys the configured Number of Nodes of the Read-only Node Type.

Click Add a node to add additional Read-only rows. You can have any number of Read-only nodes in the zone. Consider adding Read-only nodes in each region where you want to facilitate local secondary read operations.

For each shard in the zone, Atlas distributes the shard nodes with respect to the Zone Configuration. You can add additional shards to the zone by clicking Additional Options in the Zone Configuration section and selecting the total number of shards in the zone from the drop-down box. By default Atlas deploys one shard per zone. Atlas recommends creating additional zones to support heavy write load in a geographic region instead of adding multiple shards to a single zone. Atlas supports no more than 24 shards per Global Cluster.

Important

Selecting a zone template resets any configuration changes made in the Zone Configuration section to the default for the selected template.

C. Select the Cluster Tier

You must select an M30 or greater cluster instance for Global Clusters. All shard nodes deploy with the selected instance size.

From the Cluster Tier section, you can also Customize Your Storage.

Customize Your Storage

Each cluster tier comes with a default set of resources. Select your preferred storage customizations under the Customize Your Storage heading.

Atlas can provide the following storage configuration options, depending on the selected cloud provider and instance size.

  • Storage Capacity The size of the server root volume. To change this, either:

    • Move the slide bar until the text box displays your preferred disk size, or
    • Specify the exact disk size in the text box.

    Changes to storage capacity affects cost.

  • Storage Speed The input/output operations per second (IOPS) the system can perform. Changes to storage speed affect cost.

  • Auto-Expand Storage: When disk usage reaches 90%, automatically increase storage by an amount necessary to achieve 70% utilization. Changes to storage capacity affect cost. Contact Atlas support for guidance on oplog sizing for clusters with automatic storage expansion enabled.

Important

Atlas enforces a 50:1 ratio of disk storage to RAM to facilitate consistent performance of clusters with large datasets. For example, to support 1 TB of disk storage you must select a cluster tier with at least 32 GB of RAM (M50 or higher).

Atlas has a 4 TB disk storage limit on all replica sets and shards, regardless of cluster tier. To expand total cluster storage beyond 4 TB, enable sharding.

For clusters with Auto-Expand Storage enabled, Atlas respects the calculated maximum storage for the selected cluster tier. Users whose disk storage reaches the allowable limit receive notification by email.

For more information on the default resources and available configuration options for each cloud service provider, see:

D. Select any Additional Settings

Select the MongoDB Version of the Cluster

Select the MongoDB version for Atlas to deploy the cluster with from the Select a version dropdown. Atlas always deploys the cluster with the latest stable release of the specified version.

You can upgrade an existing Atlas cluster to a newer major MongoDB version, if available, when you scale a cluster. However, you cannot downgrade a cluster’s MongoDB version.

Enable Backup for the Cluster

To enable backups for the Atlas cluster, toggle Turn on Backup (M10 and up) to Yes. If enabled, Atlas takes snapshots of your databases at regular intervals and retains them according to your project’s retention policy. Atlas Global Clusters support Continuous Backups only.

The backup option chosen for the first cluster in a project dictates the backup option for all other subsequent clusters in the project. If the project has other clusters deployed using Cloud Provider Snapshots, you cannot enable backups for your Global Cluster. Consider deploying your Global Cluster to a project that permits Continuous Backups.

Enable BI Connector for Atlas

To enable the BI Connector for Atlas for this cluster, toggle Enable Business Intelligence Connector (M10 and up) to Yes.

If enabled, select the node type from which the BI Connector for Atlas should read. For high traffic production environments, the secondary node may be preferable to the primary node.

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

Enable Encryption at Rest

Configure Encryption at Rest using your Key Management for your Atlas Project

You must configure the Atlas project for Encryption at Rest using your Key Management before enabling the feature for your Atlas clusters. To learn more, see Encryption at Rest Using Your Key Management.

Atlas supports the following Encryption at Rest providers: - AWS Key Management Services - Azure Key Vault

Atlas encrypts all cluster storage and snapshot volumes, ensuring the security of all cluster data at rest (Encryption at Rest). Atlas Project Owners can configure an additional layer of encryption on their data at rest using the MongoDB Encrypted Storage Engine and their Atlas-compatible Encryption at Rest provider.

To enable Atlas Encryption at Rest for this cluster, toggle Encryption At Rest with WiredTiger Encrypted Storage Engine (M10 and up) to Yes.

Atlas Encryption at Rest using your Key Management supports M10 or greater replica set clusters backed by AWS or Azure only. Support for clusters deployed on Google Cloud Project (GCP) is in development. Atlas Encryption at Rest supports encrypting Cloud Provider Snapshots only. You cannot enable Encryption at Rest on a cluster using Continuous Backups.

Atlas clusters using Encryption at Rest using your Key Management incur an increase to their hourly run cost. For more information on Atlas billing for advanced security features, see Advanced Security.

Important

If Atlas cannot access the Atlas project key management provider or the encryption key used to encrypt a cluster, then that cluster becomes inaccessible and unrecoverable. Exercise extreme caution before modifying, deleting, or disabling an encryption key or key management provider credentials used by Atlas.

Configure Additional Configuration Options

You can configure the following mongod runtime options on M10+ paid tier clusters:

Set Oplog Size asterisk icon

Modify the oplog size of the cluster. For sharded cluster deployments, this modifies the oplog size of each shard in the cluster. This option corresponds to modifying the replication.oplogSizeMB configuration file option for each mongod in the cluster.

You can check the oplog size by connecting to your cluster via the mongo shell and authenticating as a user with the Atlas admin role. Run the rs.printReplicationInfo() method to view the current oplog size and time.

Warning

Reducing the size of the oplog requires removing data from the oplog. Atlas cannot access or restore any oplog entries removed as a result of oplog reduction. Consider the ramifications of this data loss before reducing the oplog.

Enforce Index Key Limit
Enable or disable enforcement of the 1024-byte index key limit. Documents can only be updated or inserted if, for all indexed fields on the target collection, the corresponding index entries do not exceed 1024 bytes. If disabled, mongod writes documents that breach the limit but does not index them. This option corresponds to modifying the failIndexKeyTooLong parameter via the setParameter command for each mongod in the cluster.
Allow Server-Side JavaScript
Enable or disable execution of operations that perform server-side execution of JavaScript. This option corresponds to modifying the security.javascriptEnabled configuration file option for each mongod in the cluster.
Set Minimum TLS Protocol Version asterisk icon

Sets the minimum TLS version the cluster accepts for incoming connections. This option corresponds to configuring the net.ssl.disabledProtocols configuration file option for each mongod in the cluster.

TLS 1.0 Deprecation

For users considering this option as a method for enabling the deprecated Transport Layer Security (TLS) 1.0 protocol version, please read What versions of TLS does Atlas support? before proceeding. Atlas deprecation of TLS 1.0 improves your security of data-in-transit and aligns with industry best practices. Enabling TLS 1.0 for any Atlas cluster carries security risks. Consider enabling TLS 1.0 only for as long as required to update your application stack to support TLS 1.1 or later.

Require Indexes for All Queries
Enable or disable the execution of queries that require a collection scan to return results. This option corresponds to modifying the notablescan parameter via the setParameter command for each mongod in the cluster.

asterisk icon Atlas performs uses a rolling deployment process to apply modifications to these options. For sharded clusters, this involves a rolling restart of all shards and the config server replica set. To learn more about how Atlas supports high availability during maintenance operations, see How does MongoDB Atlas deliver high availability?.

E. Enter the Cluster Name

This is the cluster name as it appears in Atlas. You cannot change the cluster name once Atlas deploys the cluster.

F. Enter your Payment Information and Deploy your Cluster

Click Confirm & Deploy to enter payment information. For Atlas M0 Free Tier cluster, Atlas does not require payment information to deploy the cluster.

See Billing Overview for more information on Atlas billing and payments.

G. (Optional) Create a MongoDB Administrative User

Atlas only allows client connections to the cluster from entries in the project IP whitelist. Clients must also authenticate as a MongoDB database user associated to the project.

If you have not configured the project IP whitelist or MongoDB users, follow the prompts in the Atlas Clusters view to configure basic project security.

When creating your first MongoDB database user, select the Atlas admin role from the user configuration dialog to create an administrative user. See MongoDB Database User Privileges for more information on MongoDB user privileges.

If you need to modify your existing project security settings, click the Security tab from the Clusters view. See Security Features and Setup for complete documentation on Atlas project security settings.

Note

To shard a collection via the mongo shell, you must authenticate as a user with the Atlas admin role, such as the administrative user created for this step.

H. Connect to your cluster

Once Atlas deploys your cluster, click Connect on the cluster to open the Connect dialog. Follow the instructions to connect to your cluster. See Connect to a Cluster for more information.