BlogAnnounced at MongoDB.local NYC 2024: A recap of all announcements and updatesLearn more >>
MongoDB Developer
Sign in to follow topics
MongoDB Developer Centerchevron-right
Developer Topicschevron-right

Getting Started With MongoDB Atlas Serverless, AWS CDK, and AWS Serverless Computing

Zuhair Ahmed, Pahud Hsieh17 min read • Published Mar 04, 2024 • Updated Mar 04, 2024
Facebook Icontwitter iconlinkedin icon
Rate this tutorial
Serverless development is a cloud computing execution model where cloud and SaaS providers dynamically manage the allocation and provisioning of servers on your behalf, dropping all the way to $0 cost when not in use. This approach allows developers to build and run applications and services without worrying about the underlying infrastructure, focusing primarily on writing code for their core product and associated business logic. Developers opt for serverless architectures to benefit from reduced operational overhead, cost efficiency through pay-per-use billing, and the ability to easily scale applications in response to real-time demand without manual intervention.
MongoDB Atlas serverless instances eliminate the cognitive load of sizing infrastructure and allow you to get started with minimal configuration, so you can focus on building your app. Simply choose a cloud region and then start building with documents that map directly to objects in your code. Your serverless database will automatically scale with your app's growth, charging only for the resources utilized. Whether you’re just getting started or already have users all over the world, Atlas provides the capabilities to power today's most innovative applications while meeting the most demanding requirements for resilience, scale, and data privacy.
In this tutorial, we will walk you through getting started to build and deploy a simple serverless app that aggregates sales data stored in a MongoDB Atlas serverless instance using AWS Lambda as our compute engine and Amazon API Gateway as our fully managed service to create a RESTful API interface. Lastly, we will show you how easy this is using our recently published AWS CDK Level 3 constructs to better incorporate infrastructure as code (IaC) and DevOps best practices into your software development life cycle (SDLC).
In this step-by-step guide, we will walk you through the entire process. We will be starting from an empty directory in an Ubuntu 20.04 LTS environment, but feel free to follow along in any supported OS that you prefer.
Let's get started!


  1. Create a MongoDB Atlas account. Already have an AWS account? Atlas supports paying for usage via the AWS Marketplace (AWS MP) without any upfront commitment — simply sign up for MongoDB Atlas via the AWS Marketplace.
  2. Create a MongoDB Atlas programmatic API key (PAK)
  3. Install and configure the AWS CLI and Atlas CLI in your terminal if you don’t have them already.
  4. Install the latest versions of Node.js and npm.
  5. Lastly, for the playground code running on Lambda function, we will be using Python so will also require Python3 and pip installed on your terminal.

Step 1: install AWS CDK, Bootstrap, and Initialize

The AWS CDK is an open-source framework that lets you define and provision cloud infrastructure using code via AWS CloudFormation. It offers preconfigured components for easy cloud application development without the need for expertise. For more details, see the AWS CDK Getting Started guide.
You can install CDK using npm:
Next, we need to “bootstrap” our AWS environment to create the necessary resources to manage the CDK apps (see AWS docs for full details). Bootstrapping is the process of preparing an environment for deployment. Bootstrapping is a one-time action that you must perform for every environment that you deploy resources into.
The cdk bootstrap command creates an Amazon S3 bucket for storing files, AWS IAM roles, and a CloudFormation stack to manage these scaffolding resources:
Now, we can initialize a new CDK app using TypeScript. This is done using the cdk init command:
This command initializes a new CDK app in TypeScript language. It creates a new directory with the necessary files and directories for a CDK app. When you initialize a new AWS CDK app, the CDK CLI sets up a project structure that organizes your application's code into a conventional layout. This layout includes bin and lib directories, among others, each serving a specific purpose in the context of a CDK app. Here's what each of these directories is for:
  • The bin directory contains the entry point of your CDK application. It's where you define which stacks from your application should be synthesized and deployed. Typically, this directory will have a <your_project_name>.ts file (with the same name as your project or another meaningful name you choose) that imports stacks from the lib directory and initializes them.
    The bin directory's script is the starting point that the CDK CLI executes to synthesize CloudFormation templates from your definitions. It acts as the orchestrator, telling the CDK which stacks to include in the synthesis process.
  • The lib directory is where the core of your application's cloud infrastructure code lives. It's intended for defining CDK stacks and constructs, which are the building blocks of your AWS infrastructure. Typically, this directory will have a <your_project_name-stack>.ts file (with the same name as your project or another meaningful name you choose).
    The lib directory contains the actual definitions of those stacks — what resources they include, how those resources are configured, and how they interact. You can define multiple stacks in the lib directory and selectively instantiate them in the bin directory as needed.

Step 2: create and deploy the MongoDB Atlas Bootstrap Stack

The [atlas-cdk-bootstrap]( CDK construct was designed to facilitate the smooth configuration and setup of the MongoDB Atlas CDK framework. This construct simplifies the process of preparing your environment to run the Atlas CDK by automating essential configurations and resource provisioning.
Key features:
  • User provisioning: The atlas-cdk-bootstrap construct creates a dedicated execution role within AWS Identity and Access Management (IAM) for executing CloudFormation Extension resources. This helps maintain security and isolation for Atlas CDK operations.
  • Programmatic API key management: It sets up an AWS Secrets Manager to securely store and manage programmatic API Keys required for interacting with the Atlas services. This ensures sensitive credentials are protected and can be easily rotated.
  • CloudFormation Extensions activation: This construct streamlines the activation of CloudFormation public extensions essential for the MongoDB Atlas CDK. It provides a seamless interface for users to specify the specific CloudFormation resources that need to be deployed and configured.
With atlas-cdk-bootstrap, you can accelerate the onboarding process for Atlas CDK and reduce the complexity of environment setup. By automating user provisioning, credential management, and resource activation, this CDK construct empowers developers to focus on building and deploying applications using the MongoDB Atlas CDK without getting bogged down by manual configuration tasks.
To use the atlas-cdk-bootstrap, we will first need a specific CDK package called awscdk-resources-mongodbatlas (see more details on this package on our
Construct Hub page). Let's install it:
To confirm that this package was installed correctly and to find its version number, see the package.json file.
Next, in the <your_project_name>.ts file in the bin directory (typically the same name as your project, i.e., cloudshell-user.ts), delete the entire contents and update with:
Next, in the <your_project_name-stack>.ts file in the lib directory (typically the same name as your project concatenated with “-stack”, i.e., cloudshell-user-stack.ts), delete the entire contents and update with:
Lastly, you can check and deploy the atlas-cdk-bootstrap CDK construct with:

Step 3: store MongoDB Atlas PAK as env variables and update AWS Secrets Manager

Now that the atlas-cdk-bootstrap CDK construct has been provisioned, we then store our previously created MongoDB Atlas programmatic API keys in AWS Secrets Manager. For more information on how to create MongoDB Atas PAK, refer to Step 2 from our prerequisites setup.
This will allow the CloudFormation Extension execution role to provision key components including: MongoDB Atlas serverless instance, Atlas project, Atlas project IP access list, and database user.
First, we must store these secrets as environment variables:
Then, we can update AWS Secrets Manager with the following AWS CLI command:

Step 4: create and deploy the atlas-serverless-basic resource CDK L3 construct

The AWS CDK Level 3 (L3) constructs are high-level abstractions that encapsulate a set of related AWS resources and configuration logic into reusable components, allowing developers to define cloud infrastructure using familiar programming languages with less code. Developers use L3 constructs to streamline the process of setting up complex AWS and MongoDB Atlas services, ensuring best practices, reducing boilerplate code, and enhancing productivity through simplified syntax.
The MongoDB Atlas AWS CDK L3 construct for Atlas Serverless Basic provides developers with an easy and idiomatic way to deploy MongoDB Atlas serverless instances within AWS environments. Under the hood, this construct abstracts away the intricacies of configuring and deploying MongoDB Atlas serverless instances and related infrastructure on your behalf.
Next, we then update our <your_project_name>.ts file in the bin directory to:
  • Add the AtlasServerlessBasicStack to the import statement.
  • Add the IP address of NAT gateway which we suggest to be the only IP address on your Atlas serverless instance access whitelist.
To leverage this, we can update our <your_project_name-stack>.ts file in the lib directory to:
  • Update import blocks for newly used resources.
  • Activate underlying CloudFormation resources on the third-party CloudFormation registry.
  • Create a database username and password and store them in AWS Secrets Manager.
  • Update output blocks to display the Atlas serverless instance connection string and project name.
Lastly, you can check and deploy the atlas-serverless-basic CDK construct with:
Verify in the Atlas UI, as well as the AWS Management Console, that all underlying MongoDB Atlas resources have been created. Note the database username and password is stored as a new secret in AWS Secrets Manager (as specified in above AWS region of your choosing).

Step 5: copy the auto-generated database username and password created in AWS Secrets Manager secret into Atlas

When we initially created the Atlas database user credentials, we created a random password, and we can’t simply copy that into AWS Secrets Manager because this would expose our database password in our CloudFormation template.
To avoid this, we need to manually update the MongoDB Atlas database user password from the secret stored in AWS Secrets Manager so they will be in sync. The AWS Lambda function will then pick this password from AWS Secrets Manager to successfully authenticate to the Atlas serverless instance.
We can do this programmatically via the Atlas CLI. To get started, we first need to make sure we have configured with the correct PAK that we created as part of our initial setup:
We then input the correct PAK and select the correct project ID. For example:
The image shows a terminal window with command line interface showing the setup process for the MongoDB Atlas CLI. Fields include: Atlas Public API Key, Atlas Private API Key, Atlas Project ID, and Output Format.
Next, we can simply update our MongoDB Atlas database user password credentials which we can copy from the AWS Management Console. This can be done with the command:
You can verify this operation by either reviewing the response from the Atlas UI (“Successfully updated database user serverless-user”) or via checking the Database Access section from the Atlas UI.

Step 6: create and deploy AWS Lambda, a Python-based Lambda function, and Amazon API Gateway CDK constructs

At this point, all your core MongoDB Atlas services should have been provisioned successfully. We next move on to provisioning the remaining AWS Lambda, Python-based Lambda function and Amazon API Gateway CDK constructs.
Next, we update our <your_project_name>.ts file in the bin directory:
  • Reference your VPC ID created in your AWS account.
    • To retrieve the VPC IDs in your AWS region that you wish to deploy into, simply use the AWS CLI command:
  • Create the AWS Lambda resource and associate with Lambda function.
  • Create the API Gateway API with the Lambda handler.
Next, we create Lambda function directories:
The Python code below is a handler function for an AWS Lambda function that interacts with the MongoDB Atlas serverless instance via a public endpoint. It fetches database credentials from AWS Secrets Manager, constructs a MongoDB Atlas connection string using these credentials, and connects to the MongoDB Atlas serverless instance.
The function then generates and inserts 20 sample sales records with random data into a sales collection within the database. It also aggregates sales data for the year 2023, counting the number of sales and summing the total sales amount by item. Finally, it prints the count of sales in 2023 and the aggregation results, returning this information as a JSON response.
Hence, we populate the Lambda/playground/ with:
Lastly, we need to create one last file that will store our requirements for the Python playground application with:
In this file, we populate with:
To then install these dependencies used in requirements.txt:
This installs all required Python packages in the playground directory and AWS CDK would bundle into a zip file which we can see from AWS Lambda console after deployment.

Step 7: create suggested AWS networking infrastructure

AWS Lambda functions placed in public subnets do not automatically have internet access because Lambda functions do not have public IP addresses, and a public subnet routes traffic through an internet gateway (IGW). To access the internet, a Lambda function can be associated with a private subnet with a route to a NAT gateway.
First, ensure that you have NAT gateway created in your public subnet. Then, create a route from a private subnet (where your AWS Lambda resource will live) to the NAT gateway and route the public subnet to IGW. The benefits of this networking approach is that we can associate a static IP to our NAT gateway so this will be our one and only Atlas project IP access list entry. This means that all traffic is still going to the public internet through the NAT gateway and is TLS encrypted. The whitelist only allows the NAT gateway static public IP and nothing else.
Alternatively, you can choose to build with AWS PrivateLink which does carry additional costs but will dramatically simplify networking management by directly connecting AWS Lambda to a MongoDB Atlas severless instance without the need to maintain subnets, IGWs, or NAT gateways. Also, AWS PrivateLink creates a private connection to AWS services, reducing the risk of exposing data to the public internet.
Select whichever networking approach best suits your organization’s needs.
The image is a diagram that illustrates the NAT Gateway Approach for connecting a cloud-based application to the internet and external services. The components of the architecture are contained within the AWS Cloud environment. Here's a description of the flow and components depicted in the image
  • An HTTP Client outside AWS Cloud sends a request to the Amazon API Gateway.
  • The Amazon API Gateway, represented by a pink icon, receives the HTTP request and passes it to AWS Lambda, symbolized by an orange icon. AWS Lambda is a serverless compute service that automatically manages the compute resources.
  • The AWS Cloud environment is divided into a Virtual Private Cloud (VPC), denoted by a blue border.
  • Inside the VPC, there are two types of subnets:
    • A Public subnet, which has direct access to the Internet via an Internet Gateway, depicted with a purple icon.
    • A Private subnet, which does not have direct access to the Internet.
  • To allow the AWS Lambda function within the Private subnet to access the Internet, a NAT (Network Address Translation) Gateway, shown with a purple NAT icon, is used. The NAT Gateway is located in the Public subnet.
  • Traffic from the AWS Lambda function is routed through the NAT Gateway to reach external services.
  • The external service that the AWS Lambda function is communicating with is a MongoDB Atlas Serverless Instance, indicated by a green icon with a database symbol. This instance is outside of the AWS Cloud and accessible over the Internet.”
The image is a schematic representation of the AWS PrivateLink Approach for securely connecting services within AWS Cloud.
The components of this architecture are as follows:
  • On the left side, an "HTTP Client" represented by a cloud icon, is initiating a request.
  • This request is sent to the "Amazon API Gateway," indicated by a pink icon with two brackets and a lightning symbol, suggesting it's an entry point for APIs.
  • Below the API Gateway, there's an "AWS Lambda" function, symbolized by an orange Lambda (λ) icon, which is a serverless computing service in AWS.
  • The Lambda function is within an "AWS Cloud" boundary, shown with a black outline.
  • Inside the AWS Cloud, there's a "Virtual private cloud (VPC)" depicted by a blue border, which is a segregated part of the AWS Cloud, isolated from other networks.
  • Within the VPC, there is a "VPC Endpoint" represented by a circular icon with a purple border and an inward-facing arrow, indicating it's a gateway for private connections.
  • The "AWS PrivateLink," shown with a purple cloud-like icon, facilitates private connectivity between services within AWS, bypassing the public internet.
  • On the far right, there's a "MongoDB Atlas Serverless Instance" depicted with a green database icon and a plug, indicating that it's an external service connected via PrivateLink.”
Finally, we are ready to check and deploy the mongodb-atlas-bootstrap-stack for the last time:

Step 8: review and test the RESTful API endpoint from the serverless application

Review AWS Management Console. See under CloudFormation and Lambda:
The image is a screenshot of the AWS Management Console, specifically within the AWS CloudFormation service. The focus of the screenshot is on a particular CloudFormation stack named "atlas-serverless-basic-stack2".
The image is a screenshot of the AWS Management Console, specifically within the AWS CloudFormation service. The focus of the screenshot is on a particular CloudFormation stack named "atlas-serverless-basic-stack2".
Click “Rest API Endpoint” to see if the Lambda function returns a response:
The image is a terminal screen with command line output related to an AWS CloudFormation stack deployment. The instruction "Click 'Rest API Endpoint' to see if the Lambda function returns a response" is guiding the user to test the deployed Lambda function by accessing the provided API Gateway URL. This is a common post-deployment step to verify that a serverless application's endpoint is operational and the Lambda function is executing as expected. When this URL is accessed (via a web browser or a tool like curl), it should invoke the Lambda function, which will process the request and return a response.
Review the Lambda function by inputting into a web browser.
The image shows the output of an AWS Lambda function when accessed via a REST API endpoint from the browser. The output is in JSON format and shows a key named "sales_2023" with a value of 6, indicating there are 6 sales records for the year 2023. Under the "results" key, there are multiple objects each with an "id" and "totalSaleAmount
The JSON structure implies that the Lambda function is working correctly, as it's able to execute and return structured data. If you need to test this Lambda function further or integrate it with other services, you would typically do so by calling this REST API endpoint from your application with the appropriate HTTP method (GET, POST, etc.), headers, and any required parameters or body content.”
Lastly, you can also curl this API endpoint:
The image is of a terminal screen showing the use of ‘curl’ command to make a request to an AWS Lambda function via a provided API endpoint. The ‘curl’ command is using the -s flag for silent mode, which means it won't show progress or error messages. The output of the curl command is being piped into ‘jq’, which is a lightweight and flexible command-line JSON processor. The ‘jq’ command is used with the -r flag to output raw strings, not JSON-quoted strings.

Step 9 (optional): tear down infrastructure to prevent unwanted charges

And then finally:
Note: This order ensures the serverless stack would be destroyed first. If you use the npx cdk destroy --all command instead, as we do not specify their stack dependency, all stacks will be deleted in parallel which may cause failures. This is because we will lose the required bootstrap resources before destroying all other resources.

All done

Congratulations! You have just deployed your first serverless application with MongoDB Atlas serverless, AWS Lambda, and Amazon API Gateway with the AWS CDK.
Next, head to YouTube for a full step-by-step overview and walkthrough on a recent episode of MongoDB TV Cloud Connect (aired 15 Feb 2024). Also, see the GitHub repo with the full open-source code of materials used in this demo serverless application.
The MongoDB Atlas CDK resources are open-sourced under the Apache-2.0 license and we welcome community contributions. To learn more, see our contributing guidelines.
Get started quickly by creating a MongoDB Atlas account through the AWS Marketplace and start building with MongoDB Atlas and the AWS CDK today!

Facebook Icontwitter iconlinkedin icon
Rate this tutorial

Flexible Querying with Atlas Search

Oct 12, 2022 | 3 min read

How to Build a Search Service in Java

Apr 23, 2024 | 11 min read

UDF Announcement for MongoDB to BigQuery Dataflow Templates

Apr 02, 2024 | 4 min read

MongoDB Atlas With Terraform: Database Users and Vault

Apr 15, 2024 | 9 min read
Table of Contents