MongoDB Atlas on AWS

Partner Solution Deployment Guide

QS

February 2023
MongoDB Inc.
Vinod Shukla, AWS Integration & Automation team

Refer to the GitHub repository to view source files, report bugs, submit feature ideas, and post feedback about this Partner Solution. To comment on the documentation, refer to Feedback.

This Partner Solution was created by MongoDB Inc. in collaboration with Amazon Web Services (AWS). Partner Solutions are automated reference deployments that help people deploy popular technologies on AWS according to AWS best practices. If you’re unfamiliar with AWS Partner Solutions, refer to the AWS Partner Solution General Information Guide.

Overview

This guide covers the information you need to deploy the MongoDB Atlas Partner Solution in the AWS Cloud.

MongoDB Atlas is a global cloud document database service for modern applications. Deploying a fully managed MongoDB helps to ensure availability, scalability, and security compliance. You can extend your data with the MongoDB cloud platform, including full-text search, mobile sync, and automated data tiering.

This Partner Solution is for developers and DevOps professionals who want to create flexible, fully managed clusters on MongoDB Atlas. The template creates an Atlas project with a standard, single-region M10 cluster and can be customized for different cluster configurations and project settings.

By default, every MongoDB Atlas cluster includes the following:

  • Support for the latest MongoDB enterprise database versions

  • A three-node (minimally) replica set for high availability, deployed into a new VPC

  • Built-in security defaults, including always-on authentication and end-to-end encryption

  • Fully managed database lifecycle with automated patches, backups, and monitoring

  • Performance optimization features such as automatic scaling, index suggestions, and intelligent data tiering

Costs and licenses

There is no cost to use this Partner Solution, but you will be billed for any AWS services or resources that this Partner Solution deploys. For more information, refer to the AWS Partner Solution General Information Guide.

If deploying a MongoDB Atlas cluster using the pay-as-you-go option, first subscribe to MongoDB Atlas (pay-as-you-go) on AWS Marketplace and then link your AWS account to your MongoDB Atlas account. For more information, refer to Link an AWS Billing Account to MongoDB Atlas.

This Partner Solution deploys MongoDB Atlas with the latest stable MongoDB enterprise version, which is licensed and distributed under the Server Side Public License (SSPL).

Architecture

Deploying this Partner Solution with default parameters builds the following MongoDB Atlas environment in the AWS Cloud.

Architecture
Figure 1. Partner Solution architecture for MongoDB Atlas on AWS

As shown in Figure 1, this Partner Solution sets up the following:

  • A VPC that spans two Availability Zones. The VPC is configured with public subnets, according to AWS best practices, to provide you with your own virtual network on AWS.*

  • In the public subnets, managed network address translation (NAT) gateways to allow outbound internet access.*

  • A VPC peering connection between your VPC and the MongoDB Atlas VPC.

  • A VPC for the MongoDB Atlas project that spans at least three Availability Zones. This includes a fully managed MongoDB Atlas cluster, a database user, and an IP access list entry.

* The template that deploys this Partner Solution into an existing VPC skips the components marked by asterisks and prompts you for your existing VPC configuration.

Deploying Atlas without peering is the simplest deployment option. It skips the VPC resources and creates only MongoDB Atlas resources using MongoDB CloudFormation resource types.

Deployment options

This Partner Solution provides the following deployment options:

For greater security, each option provisions an AWS IAM role and corresponding MongoDB database user. This Partner Solution provides separate templates for these options. It also lets you configure Classless Inter-Domain Routing (CIDR) blocks, instance types, and MongoDB Atlas settings.

Predeployment steps

Prepare your AWS account

This Partner Solution uses MongoDB Atlas CloudFormation resource types and automatically activates them in the AWS Region of your choice. Once it’s running, you can safely skip this step for additional deployments in each Region by setting the ActivateMongoDBResources parameter to No.

Prepare your MongoDB Inc. account

A MongoDB Atlas programmatic API key must be generated with the appropriate permissions and network access entries so that AWS CloudFormation can successfully authenticate the MongoDB cloud. For more information about creating and managing API keys, see Programmatic Access to Atlas.

After creating the programmatic API key, store it as a secret in AWS Secrets Manager with the following naming convention: cfn/atlas/profile/${ProfileName}. Use this CloudFormation template to create the secret in the AWS Region where this Partner Solution will be deployed.

Deployment steps

  1. Sign in to your AWS account, and launch this Partner Solution, as described under Deployment options. The AWS CloudFormation console opens with a prepopulated template.

  2. Choose the correct AWS Region, and then choose Next.

  3. On the Create stack page, keep the default setting for the template URL, and then choose Next.

  4. On the Specify stack details page, change the stack name if needed. Review the parameters for the template. Provide values for the parameters that require input. For all other parameters, review the default settings and customize them as necessary. When you finish reviewing and customizing the parameters, choose Next.

    Unless you’re customizing the Partner Solution templates or are instructed otherwise in this guide’s Predeployment section, don’t change the default settings for the following parameters: QSS3BucketName, QSS3BucketRegion, and QSS3KeyPrefix. Changing the values of these parameters will modify code references that point to the Amazon Simple Storage Service (Amazon S3) bucket name and key prefix. For more information, refer to the AWS Partner Solutions Contributor’s Guide.

  5. On the Configure stack options page, you can specify tags (key-value pairs) for resources in your stack and set advanced options. When you finish, choose Next.

  6. On the Review page, review and confirm the template settings. Under Capabilities, select all of the check boxes to acknowledge that the template creates AWS Identity and Access Management (IAM) resources that might require the ability to automatically expand macros.

  7. Choose Create stack. The stack takes about 10-20 minutes to deploy.

  8. Monitor the stack’s status, and when the status is CREATE_COMPLETE, the MongoDB Atlas deployment is ready.

  9. To view the created resources, choose the Outputs tab.

Postdeployment steps

Test the deployment

There are two ways to test your deployment:

  1. When the deployment completes, locate the new deployment project ID in the stack outputs, which you can use to open the MongoDB Atlas web console at http://cloud.mongodb.com/v2/<ProjectId>.

  2. Use the mongo shell. For more information, see Connect to a MongoDB Atlas Cluster using AWS IAM Credentials.

Best practices for using MongoDB Atlas on AWS

There are many considerations for production-grade deployments. While this Partner Solution demonstrates some of these, such as database-user security and peering, see Atlas Production Best Practices for the latest information.

Choosing the correct Atlas cluster tier and configuration is an important step in setting up a successful production MongoDB deployment. You can always modify a cluster at a later time, but getting started with the right configuration is possible with a few calculations based on your data set size and network requirements. For more information, see MongoDB Atlas Production Considerations.

Security

This Partner Solution provisions a cluster with security and TLS enabled by default. Optionally, network peering can be enabled on a new or existing AWS VPC. For more information, see MongoDB Security Features and Setup.

If you plan to use AWS Lambda, ensure that you follow the recommendations from Best Practices Connecting from AWS Lambda.

MongoDB Atlas CloudFormation resource reference

  • MongoDB::Atlas::Project — A logical grouping of clusters. You can have multiple clusters within a single project and multiple projects within a single organization.

  • MongoDB::Atlas::Cluster — A set of nodes comprising a MongoDB deployment and database. In Atlas, clusters can be replica sets or sharded deployments.

  • MongoDB::Atlas::DatabaseUser — Credentials used to authenticate a client to access a MongoDB database deployment. You can assign privileges to a database user to determine a user’s access level to a cluster. Database users are different from Atlas users. Database users have access to MongoDB deployments but not the Atlas application.

  • MongoDB::Atlas::ProjectIPAccessList — Atlas allows only client connections to the cluster from entries in the project’s IP access list. Each entry is either a single IP address or CIDR.

  • MongoDB::Atlas::NetworkPeering — Process by which two internet networks connect and exchange traffic. You can directly peer your VPC with the Atlas VPC created for your MongoDB clusters. Using network peering, your application servers can connect directly to Atlas while remaining isolated from public networks.

  • MongoDB::Atlas::PrivateEndpoint — Process by which two internet networks connect and exchange traffic. You can directly connect your VPC with the Atlas VPC created for your MongoDB clusters. Using Private Endpoint, your application servers can connect directly to Atlas allows you to privately connect without requiring an internet gateway or a NAT device.

For more information, see MongoDB::Atlas::Project, MongoDB Projects, and MongoDB Reference.

Troubleshooting

For troubleshooting common Partner Solution issues, refer to the AWS Partner Solution General Information Guide and Troubleshooting CloudFormation.

Errors can typically be resolved by inspecting the CloudFormation event logs or CloudWatch logs created by the MongoDB Atlas CloudFormation resources.

If a stack fails to deploy, check the Events tab. If the error occurs for one of the MongoDB Atlas resources (for example, MongoDB::Atlas::Cluster), you will find a corresponding Amazon CloudWatch Logs group called mongodb-atlas-cluster-logs. Locate this group, and check the latest log entry to identify the issue.

If you receive a NO_PAYMENT_INFORMATION_FOUND error message when deploying a MongoDB cluster using the pay-as-you-go option, most likely your AWS account is not linked to your MongoDB Atlas account. For more information, see the Costs and Licenses section in this guide.

FAQ

Q. Do I need to run the RegisterMongoDBResource step each time?

A. No. You must run this step only once per Region.

Q. What does the RegisterMongoDBResource step do?

A. It registers each of the MongoDB Atlas CloudFormation resource types. This is a standard requirement for CloudFormation. For more information, see Custom resource.

Customer responsibility

After you deploy a Partner Solution, confirm that your resources and services are updated and configured—including any required patches—to meet your security and other needs. For more information, refer to the Shared Responsibility Model.

Feedback

To submit feature ideas and report bugs, use the Issues section of the GitHub repository for this Partner Solution. To submit code, refer to the Partner Solution Contributor’s Guide. To submit feedback on this deployment guide, use the following GitHub links:

Notices

This document is provided for informational purposes only. It represents current AWS product offerings and practices as of the date of issue of this document, which are subject to change without notice. Customers are responsible for making their own independent assessment of the information in this document and any use of AWS products or services, each of which is provided "as is" without warranty of any kind, whether expressed or implied. This document does not create any warranties, representations, contractual commitments, conditions, or assurances from AWS, its affiliates, suppliers, or licensors. The responsibilities and liabilities of AWS to its customers are controlled by AWS agreements, and this document is not part of, nor does it modify, any agreement between AWS and its customers.

The software included with this paper is licensed under the Apache License, version 2.0 (the "License"). You may not use this file except in compliance with the License. A copy of the License is located at https://aws.amazon.com/apache2.0/ or in the accompanying "license" file. This code is distributed on an "as is" basis, without warranties or conditions of any kind, either expressed or implied. Refer to the License for specific language governing permissions and limitations.