How to Deploy MongoDB Atlas with AWS CloudFormation
Rate this tutorial
MongoDB Atlas is the multi-cloud developer data platform that provides an integrated suite of cloud database and data services. We help to accelerate and simplify how you build resilient and performant global applications on the cloud provider of your choice.
AWS CloudFormation lets you model, provision, and manage AWS and third-party resources like MongoDB Atlas by treating infrastructure as code (IaC). CloudFormation templates are written in either JSON or YAML.
While there are multiple ways to use CloudFormation to provision and manage your Atlas clusters, such as with Partner Solution Deployments or the AWS CDK, today we’re going to go over how to create your first YAML CloudFormation templates to deploy Atlas clusters with CloudFormation.
These pre-made templates directly leverage MongoDB Atlas resources from the CloudFormation Public Registry and execute via the AWS CLI/AWS Management Console. Using these is best for users who seek to be tightly integrated into AWS with fine-grained access controls.
Let’s get started!
Prerequisites:
Once you have an account created and are logged into the MongoDB Atlas UI (user interface), you will need to generate a Programmatic API Key (PAK) to authenticate with the CloudFormation resources to MongoDB Atlas.
Go to the top of the Atlas UI, click the gear icon to the right of the organization name you created, click “Access Manager” in the left-hand menu bar, click the “Create API Keys” tab, and then click the green “Create API Key” box.
Enter a description for the API key that will help you remember what it’s being used for — for example, “CloudFormation API Key.” Next, you’ll select the appropriate user permission for what you want to accomplish with CloudFormation. Both the Organization Owner and Organization Project Creator roles (see role descriptions below) provide access to complete this task, but by using the principle of least privilege, let’s select the Organization Project Creator role in the dropdown menu and click “Next.” Create a public key (which acts as a username) and then create a private key (which acts as a password).
IMPORTANT: Make sure to copy your private key and store it in a secure location. After you leave this page, your full private key will not be accessible.
When creating MongoDB programmatic API keys for Atlas Admin API, you will need to add the IP address where CloudFormation will be executed on to the IP Whitelist to ensure that only requests from specific IP addresses can access your Atlas cluster using that key. The IP Whitelist provides an additional layer of security by limiting the IP addresses that can connect to your Atlas resources. If an IP address is not whitelisted, any request originating from it will be denied.
On the same page, scroll down and click “Add Access List Entry.” If you are unsure of the IP address that CloudFormation is using to deploy your infrastructure, review the AWS IP address ranges and contact AWS support directly, who can help confirm the CIDR range to be used in your Atlas PAK IP Whitelist.
Another option is to open up your IP Access List to all, but this comes with significant potential risk. To do this, make sure to add in the appropriate organization permissions to your API key. Next, add the following two CIDRs: 0.0.0.0/1 and 128.0.0.0/1. These entries will open your IP Access List to all access — or at most, 4,294,967,296 (or 2^32) IPv4 addresses — and should be used with caution. Learn more about how to create a Programmatic API Key on MongoDB Atlas.
Before using CloudFormation, you’ll need to store the programmatic API key you created in AWS Secrets Manager. Go to the Secrets Manager tab and click “Add New Secret.” You should be taken to a page that looks like this:
From there, select “Other Type of Secret” and then add in your public and private keys. You can enter them manually or add them in the plaintext section (see below).
In plaintext, format the secret as such:
1 { "PublicKey": "YourPublicKey", "PrivateKey": "YourPrivateKey" }
On the next page, give your secret a name. In this case, it would be cfn/atlas/profile/default, the same as the one used in the previous step.
In the AWS Management Console, click on the CloudFormation button in the navigation bar. Select your region, and then in the left-hand column, select “Public Extensions” under the Registry drop-down. Select “Resource types” under extension type and “Third party” under publisher.
Make sure to activate your AWS CloudFormation resources in the AWS region from which you wish to deploy your CloudFormation resources. In this example, we deploy from N. Virginia (us-east-1).
Once a list of resources populates after making your selections, you’ll need to select which resources you need. You will need to use the resources defined by your template. Some example resources include:
- MongoDB::Atlas::Project
- MongoDB::Atlas::Cluster
- MongoDB::Atlas::DatabaseUser
- MongoDB::Atlas::ProjectIpAccessList
You can find the resources your template needs outlined in the template.
When you select your resources, you will need to provide an ARN (Amazon Resource Names). You can set this up with AWS IAM (Identity and Access Management). You can find that in the navigation bar of your AWS. You can find the ARN in the user information in the “Roles” button. Once there, find the role whose ARN you want to use and add it to the Extension Details in CloudFormation. Learn how to create user roles/permissions in the IAM.
Once your ARN has been added in, click “Activate” and your permissions will be activated. See a sample AWS ARN required from our GitHub repo. It’s important that you use an ARN with sufficient permissions each time it’s asked for.
Additionally, you can add in this trust relationship string to ensure that the admin or other users are able to perform CloudFormation functions. The following example outlines how to add this string to the space in the Trust relationships section:
1 { 2 "Version": "2012-10-17", 3 "Statement": [ 4 { 5 "Sid": "Statement1", 6 "Effect": "Allow", 7 "Principal": { 8 "AWS": "resource.cloudformation.amazonaws.com" 9 }, 10 "Action": "sts:AssumeRole" 11 } 12 ] 13 }
Note: Broad IAM access is not recommended for production workloads but may be sufficient for testing.
In this example, I have opted in to automatically update versions. This step is optional.
If you would rather use a sample CloudFormation template in YAML than create your own, you can find it in the MongoDB git repository.
In the AWS management console, go to the CloudFormation tab. Then, in the left-hand navigation, click on “Stacks.” In the window that appears, hit the “Create Stack” drop-down. Select “Create new stack with existing resources.”
Next, select “template is ready” in the “Prerequisites” section and “Upload a template” in the “Specify templates” section. From here, you will choose the YAML (or JSON) file containing the MongoDB Atlas deployment that you created in the prior step.
Next, you’ll need to specify stack details by filling out the stack name and the parameters. It’s important that the information on this page lines up with the script in the template. For example, you’ll need to make sure that the name of your AWS Secret Manager secret (in this case, “default”) is the same as what you used in your deployment.
Then, configure your stack options with tags, permissions, and stack failure options. Choose a unique database user password.
Finally, review your stack, hit “Submit,” and you’re set! Note deploying a MongoDB Atlas cluster for the first time can take seven to 10 minutes. You can check the status in the Atlas UI.
Congratulations! You have just deployed MongoDB Atlas resources with AWS CloudFormation.
The MongoDB Atlas CloudFormation resources are open-sourced under the Apache-2.0 license and we welcome community contributions. To learn more, see our contributing guidelines.
Additionally, you can watch our demo to learn about the other ways to get started with MongoDB Atlas and CloudFormation
Go build with MongoDB Atlas and AWS CloudFormation today!
Rate this tutorial