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

  • Auto-Expand Storage: When disk usage reaches 90%, automatically increase storage by an amount necessary to achieve 70% utilization. Changes to storage capacity affects cost.

    Note

    If the size of the cluster oplog is small, Atlas may be unable to automatically expand disk capacity.

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.

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.