Zuhair Ahmed

Sr. Product Manager

Pahud Hsieh

Senior Solutions Architect at AWS

Build an app that aggregates sales data stored in an Atlas serverless instance using AWS Lambda and Amazon API Gateway to create a RESTful API interface.

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

Rutuja Rajwade

Product Marketing Manager

An event-driven architecture is a highly effective framework for creating applications that are responsive, scalable, and maintainable with loosely coupled components. This approach has become essential in developing applications that can rapidly respond to customer demands and dynamic market conditions.

For example, in healthcare, event-driven systems process data emitted by medical devices (like ECGs and blood glucose monitors) to provide real-time insights and alerts to healthcare providers, enabling timely interventions. Financial institutions utilize event-driven architectures to process and analyze transactions in real time. This allows for immediate fraud detection, risk assessment, and dynamic pricing based on current market conditions.

In this tutorial, we cover how to get started with MongoDB Atlas for near real-time data processing with HashiCorp Terraform. By integrating [MongoDB Atlas Stream Processing](https://www.mongodb.com/products/platform/atlas-stream-processing) with the [HashiCorp Terraform MongoDB Atlas Provider](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest), developers can efficiently manage real-time data workflows and automate resource provisioning.

Let’s get started!

## Prerequisites

- Create a [MongoDB Atlas](https://www.mongodb.com/cloud/atlas/register) account. (More configuration details will be shown below.)
- Install [HashiCorp Terraform](https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli) on your terminal or sign up for a free [Terraform Cloud](https://app.terraform.io/public/signup/account) account.
- Create [MongoDB Atlas programmatic API keys](https://www.mongodb.com/docs/atlas/configure-api-access/#grant-programmatic-access-to-service) and [associate them with Terraform](https://www.mongodb.com/developer/products/atlas/deploy-mongodb-atlas-terraform-aws/) (further details below).
- Choose your IDE. For this tutorial, we will be using [VS Code](https://code.visualstudio.com/).

## Deploy foundational Atlas Stream Processing resources using the Terraform provider 

There are three main components to consider with Atlas Stream Processing: 

- [Stream Processing Instance](https://www.mongodb.com/docs/atlas/atlas-sp/overview/#mongodb-expression-exp.Stream-Processing-Instance) (SPI) — This acts as the primary environment where your streaming data processes are executed. It's responsible for managing and executing the stream processing tasks, maintaining performance, and ensuring data integrity throughout the streaming lifecycle.
- [Connection registry](https://www.mongodb.com/docs/atlas/atlas-sp/overview/#mongodb-expression-exp.Connection-Registry) — This serves as the conduit between your data sources/sinks and the processing instance. It's tasked with the secure and efficient transport of streaming data, facilitating continuous data ingestion from various sources into the SPI.
- [Stream processor](https://www.mongodb.com/docs/atlas/atlas-sp/overview/#mongodb-expression-exp.Stream-Processor) — This is where the business logic for data transformation and analysis is defined and executed. Using MongoDB's expressive querying and aggregation capabilities, this component processes incoming data streams continuously, enabling immediate data manipulation and enrichment before forwarding it for storage or further processing.

At this time, the Terraform Atlas Provider supports management of the SPI ([mongodbatlas_stream_instance](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/resources/stream_instance)) and connections in the Connection Registry ([mongodbatlas_stream_connection](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/resources/stream_connection)), with programmatic support for stream processors coming in the future. 

First, we need to deploy basic Atlas resources to get started. As part of this tutorial, this includes an Atlas project, M10 dedicated Atlas cluster, database user, and IP access list entry. 

In addition, we will be deploying one Stream Processing Instance and two connections in the connection registry. See our Atlas Admin [Open API Specification documentation](https://www.mongodb.com/docs/atlas/reference/api-resources-spec/v2/#tag/Streams/operation/createStreamInstance) for a full list of supported cloud providers, regions, and all other parameter inputs for these resources:

- In this example, our Stream Processing Instance will be hosted on AWS us-east-1 using an SP30 tier. More information on Stream Processing tiers is available in the [documentation](https://www.mongodb.com/docs/atlas/billing/stream-processing-costs/).
- For the connection registry, we will point our data source to type [Sample](https://www.mongodb.com/docs/atlas/atlas-stream-processing/tutorial/#add-the-sample-stream-connection-to-the-connection-registry.) (solar data that we provide as a sample source to use when getting started) which is great for testing purposes. (Type Kafka is also supported.)
- For a connection to the built-in sample_stream_solar, provide a configuration file with the following syntax:

```
{
  "name": "sample_stream_solar",
  "type": "Sample"
}
```

- Our data sink will point to the M10 dedicated Atlas cluster we mentioned earlier. 
- In the sample Terraform script provided below, replace the “org_id” field, and enter your own organization’s ID and your unique username and password in the “username” and “password” fields.
- Ensure that the IP address added to the script matches the one in Terraform. If you are unsure of the IP address that you are running Terraform on (and you are performing this step from that machine), simply click “Use Current IP Address and Save”. Another option is to open up your IP access list to all, but this comes with significant potential risks. To do this, you can 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, at most, 4,294,967,296 (or 2^32) IPv4 addresses and should be used with caution.

See the below Terraform script as part of our `main.tf` file.

```
terraform {
  required_providers {
    mongodbatlas = {
      source = "mongodb/mongodbatlas"
    }
  }
  required_version = ">= 0.13"
}

resource "mongodbatlas_project" "testProject" {
  name   = "testProject16"
  org_id = "[YOUR ORG_ID]"
}

resource "mongodbatlas_project_ip_access_list" "testIPAccessList" {
  project_id = mongodbatlas_project.testProject.id
  ip_address = "[YOUR IP ADDRESS]"
}

resource "mongodbatlas_database_user" "testUser" {
  project_id         = mongodbatlas_project.testProject.id
  username           = "[YOUR USERNAME]"
  password           = "[YOUR PASSWORD]"
  auth_database_name = "admin"
  roles {
    role_name     = "readWrite"
    database_name = "dbforApp"
  }
}

resource "mongodbatlas_advanced_cluster" "testCluster" {
  project_id   = mongodbatlas_project.testProject.id
  name         = "testCluster"
  cluster_type = "REPLICASET"
  replication_specs {
    region_configs {
      electable_specs {
        instance_size = "M10"
        node_count    = 3
      }
      provider_name = "AWS"
      priority      = 7
      region_name   = "US_EAST_1"
    }
  }
}

resource "mongodbatlas_stream_instance" "myFirstStreamInstance" {
  project_id    = mongodbatlas_project.testProject.id
  instance_name = "myFirstStreamInstance"
  data_process_region = {
    region         = "VIRGINIA_USA"
    cloud_provider = "AWS"
  }
  stream_config = {
    tier = "SP30"
  }
}

resource "mongodbatlas_stream_connection" "dataSource" {
    project_id = mongodbatlas_project.testProject.id
    instance_name = mongodbatlas_stream_instance.myFirstStreamInstance.instance_name
    connection_name = "sample_stream_solar"
    type = "Sample"
}

resource "mongodbatlas_stream_connection" "dataSink" {
    project_id = mongodbatlas_project.testProject.id
    instance_name = mongodbatlas_stream_instance.myFirstStreamInstance.instance_name
    connection_name = "dataSink"
    type = "Cluster"
    cluster_name = mongodbatlas_advanced_cluster.testCluster.name
    db_role_to_execute = {
      role = "atlasAdmin"
      type = "BUILT_IN"
    }
}
```

Note: Before deploying, be sure to store your MongoDB Atlas programmatic API keys created as part of prerequisites as [Environment Variables](https://developer.hashicorp.com/terraform/cli/config/environment-variables). To deploy, you can use the below commands from the terminal: 

```
terraform init 
terraform plan
terraform apply 
```

If your deployment was successful, you should be greeted with “Apply complete!” 

![Screenshot of completed deployment][1]

To confirm, you should be able to see your newly created SPI in the Atlas UI. (To navigate from the home screen, click on “Stream Processing” on the left-hand menu.) 

![Screenshot of Atlas UI after creation of stream processing instance][2]

By going into the Connection Registry, we can also verify that our connections were successfully created. 

![Screenshot of Atlas UI showcasing connection registry][3]

## Get connection string and create stream processor 

Next, you’ll need to retrieve the Atlas Stream Processing connection string and create your first stream processor.

While still in the Atlas UI, click “Connect” and select the tool to access your data through MongoDB Shell or MongoDB for VS Code. 

![Screenshot of Atlas UI showcasing connection to MongoDB Shell and MongoDB VSCode][4]

This will generate your connection string which you can use to connect to your Stream Processing Instance. 

At this point, your first stream processors can be created to define how your data will be processed in your SPI. As mentioned earlier, there are currently no Terraform resources as of yet to provide this configuration. To learn more about how stream processors can be configured, refer to [Manage Stream Processors](https://www.mongodb.com/docs/atlas/atlas-sp/manage-stream-processor/#manage-stream-processors).

For more detailed information, also see our [Atlas Stream Processing example](https://github.com/mongodb/terraform-provider-mongodbatlas/blob/master/examples/mongodbatlas_stream_instance/atlas-streams-user-journey.md) in our Terraform repo. 

## All done 

Congratulations! You have everything that you need now to run your first [Atlas Stream Processing](https://www.mongodb.com/docs/atlas/atlas-sp/overview/)-based workflow. 

With the above steps, teams can utilize Atlas Stream Processing capabilities within the Terraform MongoDB Atlas Provider. Whether you are developing complex event processing systems, real-time analytics, or interactive user engagement features, Atlas Stream Processing integrated with Terraform provides a robust infrastructure to support scalable and resilient applications. 

The HashiCorp Terraform Atlas Provider is open-sourced under the [Mozilla Public License v2.0](https://github.com/mongodb/terraform-provider-mongodbatlas?tab=MPL-2.0-1-ov-file) and we welcome community contributions. To learn more, see our [contributing guidelines](https://github.com/mongodb/terraform-provider-mongodbatlas/blob/master/CONTRIBUTING.md). 

The fastest way to get started is to create a MongoDB Atlas account from the [AWS Marketplace](https://aws.amazon.com/marketplace/seller-profile?id=c9032c7b-70dd-459f-834f-c1e23cf3d092). To learn more about the Terraform Provider, check out our [documentation](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs), [tutorials](https://www.mongodb.com/developer/search/?s=Terraform&sortMode=0), [solution brief](https://www.mongodb.com/collateral/build-resilient-applications-with-mongodb-atlas-and-hashicorp-terraform), or [get started today](https://cloud.mongodb.com).

Go build with MongoDB Atlas and the HashiCorp Terraform Atlas Provider today! 


  [1]: https://images.contentstack.io/v3/assets/blt39790b633ee0d5a7/bltd8b6fd1c026e0dfa/664bc07e1983ea56f5ac2899/1.png
  [2]: https://images.contentstack.io/v3/assets/blt39790b633ee0d5a7/bltc57e0777ae3b69f3/664bc0907853391c269e3c1f/2.png
  [3]: https://images.contentstack.io/v3/assets/blt39790b633ee0d5a7/bltb73dbc3b43a2e8a0/664bc09f941bc85c3f9df7b1/3.png
  [4]: https://images.contentstack.io/v3/assets/blt39790b633ee0d5a7/blt6e9c931aa8a32787/664bc0ae55b39716c16049d8/4.png

How to Get Started with MongoDB Atlas Stream Processing and the HashiCorp Terraform MongoDB Atlas Provider

Last year, MongoDB announced the general availability of [Atlas Vector Search](https://www.mongodb.com/blog/post/introducing-atlas-vector-search-build-intelligent-applications-semantic-search-ai), a new capability in Atlas that allows developers to search across data stored in MongoDB based on its semantic meaning using high dimensional vectors (i.e., “embeddings”) created by machine learning models. 

This allows developers to build intelligent applications that can understand and process human language in a way traditional, text-based search methods cannot since they will only produce an exact match for the query. 

For example, searching for “warm winter jackets” on an e-commerce website that only supports text-based search might return products with the exact match keywords "warm," "winter," and "jackets." Vector search, on the other hand, understands the semantic meaning of "warm winter jackets'' as apparel designed for cold temperatures. It retrieves items that are not only labeled as "winter jackets” but are specifically designed for warmth, including products that might be described with related terms like "insulated," giving users more helpful search results. 

Integrating Atlas Vector Search with infrastructure-as-code (IaC) tools like HashiCorp Terraform can then streamline and optimize your development workflows, ensuring that sophisticated search capabilities are built directly into the infrastructure deployment process. 

This guide will walk you through how to get started with Atlas Vector Search through our [HashiCorp Terraform Atlas provider](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest). Let’s get started! 

### Pre-requisites

 - Create a [MongoDB Atlas](https://www.mongodb.com/cloud/atlas/register) account. 
 - Install [HashiCorp Terraform](https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli) on your terminal or sign up for a free [Terraform Cloud](https://app.terraform.io/public/signup/account) account.
 - Create [MongoDB Atlas programmatic API keys](https://www.mongodb.com/docs/atlas/configure-api-access/#grant-programmatic-access-to-service) and [associate them with Terraform](https://www.mongodb.com/developer/products/atlas/deploy-mongodb-atlas-terraform-aws/). 
 - Select an IDE of your choice. For this tutorial, we will be using [VS Code](https://code.visualstudio.com/).

## Step 1: Deploy Atlas dedicated cluster with Atlas Search Nodes

First, we need to deploy basic Atlas resources to get started. This includes an Atlas project, an M10 dedicated Atlas cluster (which is pay-as-you-go, great for development and low-traffic applications), a database user, and an IP Access List Entry. 

**Note**: When configuring your MongoDB Atlas cluster with Terraform, it's important to restrict IP access to only the IP address from which the Terraform script will be deployed. This minimizes the risk of unauthorized access. 

In addition, as part of this tutorial, we will be using [Atlas Search Nodes](https://www.mongodb.com/blog/post/search-nodes-now-public-preview-performance-scale-dedicated-infrastructure) (optional). These provide dedicated infrastructure for [Atlas Search](https://www.mongodb.com/cloud/atlas/lp/search) and [Vector Search](https://www.mongodb.com/products/platform/atlas-vector-search) workloads, allowing you to fully scale search independent of database needs. Incorporating Search Nodes into your Atlas deployment allows for better performance at scale and delivers workload isolation, higher availability, and the ability to optimize resource usage. 

Lastly, when using Terraform to manage infrastructure, it is recommended to maintain organized file management practices. Typically, your Terraform configurations/scripts will be written in files with the `.tf` extension, such as `main.tf`. This file, which we are using in this tutorial, contains the primary configuration details for deploying resources and should be located ideally in a dedicated project directory on your local machine or on Terraform Cloud. 

See the below Terraform script as part of our `main.tf` file: 

```
terraform {
  required_providers {
    mongodbatlas = {
      source = "mongodb/mongodbatlas"
    }
  }
  required_version = ">= 0.13"
}

resource "mongodbatlas_project" "exampleProject" {
  name   = "exampleProject"
  org_id = "63234d3234ec0946eedcd7da"
}

resource "mongodbatlas_advanced_cluster" "exampleCluster" {
  project_id   = mongodbatlas_project.exampleProject.id
  name         = "ClusterExample"
  cluster_type = "REPLICASET"

  replication_specs {
    region_configs {
      electable_specs {
        instance_size = "M10"
        node_count    = 3
      }
      provider_name = "AWS"
      priority      = 7
      region_name   = "US_EAST_1"
    }
  }
}

resource "mongodbatlas_search_deployment" "exampleSearchNode" {
  project_id   = mongodbatlas_project.exampleProject.id
  cluster_name = mongodbatlas_advanced_cluster.exampleCluster.name
  specs = [
    {
      instance_size = "S20_HIGHCPU_NVME"
      node_count    = 2
    }
  ]
}

resource "mongodbatlas_database_user" "testUser" {
  username           = "username123"
  password           = "password-test123"
  project_id         = mongodbatlas_project.exampleProject.id
  auth_database_name = "admin"

  roles {
    role_name     = "readWrite"
    database_name = "dbforApp"
  }
}

resource "mongodbatlas_project_ip_access_list" "test" {
  project_id = mongodbatlas_project.exampleProject.id
  ip_address = "174.218.210.1"
}
```

**Note**: Before deploying, be sure to store your MongoDB Atlas programmatic API keys created as part of the prerequisites as [environment variables](https://developer.hashicorp.com/terraform/cli/config/environment-variables). To deploy, you can use the below commands from the terminal: 

```
terraform init 
terraform plan
terraform apply 
```

## Step 2: Create your collections with vector data 

For this tutorial, you can create your own collection of vectorized data if you have data to use. 

Alternatively, you can use our [sample data](https://www.mongodb.com/docs/atlas/sample-data/). This is great for testing purposes. The collection you can use is the "sample_mflix.embedded_movies" which already has embeddings generated by Open AI. 

To use sample data, from the Atlas UI, go into the Atlas cluster Overview page and select “Atlas Search” at the top of the menu presented. 
![(Cluster Overview in the Atlas UI)](https://images.contentstack.io/v3/assets/blt39790b633ee0d5a7/blt5c0ebd39059d0e07/6627cb3b776d0cbe1d24d57a/Screenshot_2024-04-23_at_10.52.09_AM.png)

Then, click “Load a Sample Dataset.”
![(Atlas Search menu in the Atlas UI)](https://images.contentstack.io/v3/assets/blt39790b633ee0d5a7/bltae4597ed96ca2b63/6627cb85210d90f4f03a44b4/Screenshot_2024-04-23_at_10.53.44_AM.png)

## Step 3: Add vector search index in Terraform configuration 

Now, head back over to Terraform and create an Atlas Search index with type “vectorSearch.” If you are using the sample data, also include a reference to the database “sample_mflix” and the collection “embedded_movies.” 

Lastly, you will need to set the “fields” parameter as per our example below. See our documentation to learn more about [how to index fields for vector search](https://www.mongodb.com/docs/atlas/atlas-vector-search/vector-search-type/#how-to-index-fields-for-vector-search) and the associated required parameters. 

```
resource "mongodbatlas_search_index" "test-basic-search-vector" {
  name   = "test-basic-search-index"  
  project_id = mongodbatlas_project.exampleProject.id
  cluster_name = mongodbatlas_advanced_cluster.exampleCluster.name
  type = "vectorSearch"
  database = "sample_mflix"
  collection_name = "embedded_movies"
  fields = <<-EOF
    [{
        "type": "vector",
        "path": "plot_embedding",
        "numDimensions": 1536,
        "similarity": "euclidean"
    }]
    EOF
}
```

To deploy again, you can use the below commands from the terminal: 
```
terraform init 
terraform plan
terraform apply 
```

If your deployment was successful, you should be greeted with “Apply complete!” 
![(Terraform in terminal showcasing deployment)](https://images.contentstack.io/v3/assets/blt39790b633ee0d5a7/bltded5c4cdf9b4a083/6627cbeae7ce95db12de9b09/Screenshot_2024-04-23_at_10.55.27_AM.png)

To confirm, you should be able to see your newly created Atlas Search index resource in the Atlas UI with Index Type “vectorSearch” and Status as “ACTIVE.” 
![(Atlas UI showcasing Vector Search deployment)](https://images.contentstack.io/v3/assets/blt39790b633ee0d5a7/blt23db256850afad56/6627cc13bb637218621defb9/Screenshot_2024-04-23_at_10.56.10_AM.png)

## Step 4: Get connection string and connect to the MongoDB Shell to begin Atlas Vector Search queries 

While still in the Atlas UI, go back to the homepage, click “Connect” on your Atlas cluster, and select “Shell.” 

![(Atlas UI page where you can choose a cluster connection method)](https://images.contentstack.io/v3/assets/blt39790b633ee0d5a7/blt95d147e9c622bd5d/6627cc47e7ce95a8b8de9b1a/Screenshot_2024-04-23_at_10.56.59_AM.png)

This will generate your connection string which you can use in the MongoDB Shell to connect to your Atlas cluster. 

### All done

Congratulations! You have everything that you need now to run your first [Vector Search queries](https://www.mongodb.com/docs/atlas/atlas-vector-search/vector-search-stage/).

With the above steps, teams can leverage Atlas Vector Search indexes and dedicated Search Nodes for the Terraform MongoDB Atlas provider to build a retrieval-augmented generation, semantic search, or recommendation system with ease. 

The HashiCorp Terraform Atlas provider is open-sourced under the [Mozilla Public License v2.0](https://github.com/mongodb/terraform-provider-mongodbatlas?tab=MPL-2.0-1-ov-file) and we welcome community contributions. To learn more, see our [contributing guidelines](https://github.com/mongodb/terraform-provider-mongodbatlas/blob/master/CONTRIBUTING.md).

The fastest way to get started is to create a MongoDB Atlas account from the [AWS Marketplace](https://aws.amazon.com/marketplace/seller-profile?id=c9032c7b-70dd-459f-834f-c1e23cf3d092) or [Google Cloud Marketplace](https://console.cloud.google.com/marketplace/product/mongodb/mdb-atlas-self-service?pli=). To learn more about the Terraform provider, check out the [documentation](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs), [solution brief](https://www.mongodb.com/collateral/build-resilient-applications-with-mongodb-atlas-and-hashicorp-terraform), and [tutorials](https://www.mongodb.com/developer/search/?s=Terraform&sortMode=0), or [get started today](https://account.mongodb.com/account/login?signedOut=true&n=https%3A%2F%2Fcloud.mongodb.com%2Fgo%3Fl%3Dhttps%253A%252F%252Fcloud.mongodb.com%252Fv2%252F%253Cproject%253E%2523%252FdataFederation%26_ga%3D2.121590028.567858162.1702935684-1592895210.1668436484%26_gac%3D1.90809704.1702935684.CjwKCAiA-P-rBhBEEiwAQEXhH1-PuNDJyW2Z4QzJDKtcrNGmvK965-IyQbQ-bitpEZxRCffLHhX-KRoC1HsQAvD_BwE).  

Go build with MongoDB Atlas and the HashiCorp Terraform Atlas provider today! 



Learn how to leverage Atlas Vector Search with HashiCorp Terraform in this tutorial.

Leveraging Atlas Vector Search With HashiCorp Terraform: Empowering Semantic Search in Modern Applications

A beginner’s guide to start deploying Atlas clusters today with Infrastructure as Code best practices

How to Deploy MongoDB Atlas with Terraform on AWS

Andrea Angiolillo

Senior Software Engineer

[MongoDB Atlas](https://www.mongodb.com/atlas), the industry’s leading developer data platform, simplifies application development and working with data for a wide variety of use cases, scales globally, and [optimizes for price/performance](https://www.mongodb.com/use-cases/serverless) as your data needs evolve over time. With Atlas, you can address the needs of modern applications faster to accelerate your go-to-market timelines, all while reducing data infrastructure complexity. Atlas offers a variety of features such as cloud backups, search, and easy integration with other cloud services. 

[AWS Cloud Development Kit (CDK)](https://aws.amazon.com/cdk/) is a tool provided by Amazon Web Services (AWS) that allows you to define infrastructure as code using familiar programming languages such as TypeScript, JavaScript, Python, Java, Go, and C#. 

MongoDB recently announced the [GA for Atlas Integrations for CDK](https://www.mongodb.com/blog/post/atlas-integrations-aws-cloud-formation-cdk-now-generally-available). This is an ideal use case for teams that want to leverage the TypeScript ecosystem and no longer want to manually provision [AWS CloudFormation](https://www.mongodb.com/atlas/aws-cloudformation) templates in YAML or JSON. Not a fan of TypeScript? No worries! MongoDB Atlas CDK Integrations also now support Python, Java, C#, and Go.

In this step-by-step guide, we will walk you through the entire process. Let's get started! 

## Setup

Before we start, you will need to do the following:

- Open a [MongoDB Atlas account ](https://aws.amazon.com/marketplace/pp/prodview-pp445qepfdy34)
✅ Already have an AWS account? Atlas supports paying for usage via the AWS Marketplace (AWS MP) without any upfront commitment — simply <a href="https://aws.amazon.com/marketplace/pp/prodview-pp445qepfdy34?trk=38088f03-4928-4b00-9a39-86781df6ab9b&sc_channel=el" target="_blank" rel="noreferrer">sign up for MongoDB Atlas via AWS Marketplace.<a>

- [Create a MongoDB Atlas Programmatic API Key (PAK)](https://www.mongodb.com/docs/atlas/configure-api-access/#create-an-api-key-in-an-organization)

- Install and configure an [AWS Account + AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-quickstart.html#getting-started-prereqs-keys)

- [Store your MongoDB Atlas PAK in AWS Secret Manager ](https://github.com/mongodb/awscdk-resources-mongodbatlas/tree/main/examples#cloudformation-profile)

- [Activate the below CloudFormation resources in the AWS region of your choice](https://docs.spot.io/tools-and-provisioning/cloudformation/activate-a-resource-in-public-extensions-registry) 

    - MongoDB::Atlas::Project
    - MongoDB::Atlas::Cluster
    - MongoDB::Atlas::DatabaseUser
    - MongoDB::Atlas::ProjectIpAccessList

## Step 1: Install AWS CDK

The AWS CDK is an open-source software (OSS) development framework for defining cloud infrastructure as code and provisioning it through [AWS CloudFormation](https://aws.amazon.com/cloudformation/). It provides high-level components that preconfigure cloud resources with proven defaults, so you can build cloud applications without needing to be an expert. You can install it globally using npm:

```bash
npm install -g aws-cdk
```

This command installs AWS CDK. The optional -g flag allows you to use it globally anywhere on your machine.

## Step 2: Bootstrap CDK

Next, we need to bootstrap our AWS environment to create the necessary resources to manage the CDK apps. The `cdk bootstrap` command creates an Amazon S3 bucket for storing files and a CloudFormation stack to manage the resources.

```bash
cdk bootstrap aws://ACCOUNT_NUMBER/REGION
```

Replace ACCOUNT_NUMBER with your AWS account number, and REGION with the AWS region you want to use.

## Step 3: Initialize a New CDK app

Now we can initialize a new CDK app using TypeScript. This is done using the `cdk init` command:

```bash
cdk init app --language typescript
```

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.

## Step 4: Install MongoDB Atlas CDK

To manage MongoDB Atlas resources, we will need a specific CDK module called awscdk-resources-mongodbatlas (see more details on this package on our [Construct Hub page](https://constructs.dev/packages/awscdk-resources-mongodbatlas/v/1.0.1?lang=typescript)). Let's install it:

```bash
npm install awscdk-resources-mongodbatlas
```

This command installs the MongoDB Atlas CDK module, which will allow us to define and manage MongoDB Atlas resources in our CDK app.

## Step 5: Replace the generated file with AtlasBasic CDK L3 repo example

Feel free to start coding if you are familiar with CDK already or if it’s easier, you can leverage the AtlasBasic CDK resource [example in our repo](https://github.com/mongodb/awscdk-resources-mongodbatlas/blob/main/examples/l3-resources/atlas-basic.ts) (also included below). This is a simple [CDK Level 3 resource](https://aws.amazon.com/blogs/devops/leverage-l2-constructs-to-reduce-the-complexity-of-your-aws-cdk-application/) that deploys a MongoDB Atlas project, cluster, database user, and project IP access List resources on your behalf. All you need to do is paste this in your “lib/YOUR_FILE.ts” directory, making sure to replace the generated file that is already there (which was created in Step 3). 

Please make sure to replace the `export class CdkTestingStack extends cdk.Stack` line with the specific folder name used in your specific environment. No other changes are required. 

```javascript
// This CDK L3 example creates a MongoDB Atlas project, cluster, databaseUser, and projectIpAccessList

import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { AtlasBasic } from 'awscdk-resources-mongodbatlas';

interface AtlasStackProps {
    readonly orgId: string;
    readonly profile: string;
    readonly clusterName: string;
    readonly region: string;
    readonly ip: string;
}

//Make sure to replace "CdkTestingStack" with your specific folder name used 
export class CdkTestingStack extends cdk.Stack {

    constructor(scope: Construct, id: string, props?: cdk.StackProps) {
        super(scope, id, props);

        const atlasProps = this.getContextProps();
        const atlasBasic = new AtlasBasic(this, 'AtlasBasic', {
            clusterProps: {
                name: atlasProps.clusterName, 
                replicationSpecs:  [
                    {
                        numShards: 1,
                        advancedRegionConfigs: [
                            {
                                analyticsSpecs: {
                                    ebsVolumeType: "STANDARD",
                                    instanceSize: "M10",
                                    nodeCount: 1
                                },
                                electableSpecs: {
                                    ebsVolumeType: "STANDARD",
                                    instanceSize: "M10",
                                    nodeCount: 3
                                },
                                priority: 7,
                                regionName: atlasProps.region,
                            }]
                    }]    
            },
            projectProps: {
                orgId: atlasProps.orgId,
            },
            ipAccessListProps: {
                accessList:[
                    { ipAddress: atlasProps.ip, comment: 'My first IP address' }
                ]
            },
            profile: atlasProps.profile,
        });
    }

    getContextProps(): AtlasStackProps {
        const orgId = this.node.tryGetContext('orgId');

        if (!orgId){
            throw "No context value specified for orgId. Please specify via the cdk context."
        }

        const profile = this.node.tryGetContext('profile') ?? 'default';
        const clusterName = this.node.tryGetContext('clusterName') ?? 'test-cluster';
        const region = this.node.tryGetContext('region') ?? "US_EAST_1";
        const ip = this.node.tryGetContext('ip');
        
        if (!ip){
            throw "No context value specified for ip. Please specify via the cdk context."
        }
        
        return {
            orgId,
            profile,
            clusterName,
            region,
            ip
        }
    }
}
```

## Step 6: Compare the deployed stack with the current state

It's always a good idea to check what changes the CDK will make before actually deploying the stack. Use `cdk diff` command to do so:

```bash
cdk diff --context orgId="YOUR_ORG" --context ip="YOUR_IP"
```

Replace YOUR_ORG with your MongoDB Atlas organization ID and YOUR_IP with your IP address. This command shows the proposed changes to be made in your infrastructure between the deployed stack and the current state of your app, notice highlights for any resources to be created, deleted, or modified. This is for review purposes only. No changes will be made to your infrastructure. 

## Step 7: Deploy the app

Finally, if everything is set up correctly, you can deploy the app:

```bash
cdk deploy --context orgId="YOUR_ORG" --context ip="YOUR_IP"
```

Again, replace YOUR_ORG with your MongoDB Atlas organization ID and YOUR_IP with your IP address. This command deploys your app using AWS CloudFormation.

## (Optional) Step 8: Clean up the deployed resources

Once you're finished with your MongoDB Atlas setup, you might want to clean up the resources you've provisioned to avoid incurring unnecessary costs. You can destroy the resources you've created using the cdk destroy command:

```bash
cdk destroy --context orgId="YOUR_ORG" --context ip="YOUR_IP"
```

This command will destroy the CloudFormation stack associated with your CDK app, effectively deleting all the resources that were created during the deployment process.

Congratulations! You have just deployed MongoDB Atlas with AWS CDK in TypeScript. Next, head to YouTube for a [full video step-by-step walkthrough and demo](https://www.youtube.com/watch?v=p7Fru0fbmxY).

[The MongoDB Atlas CDK resources](https://constructs.dev/packages/awscdk-resources-mongodbatlas/v/1.0.1?lang=typescript) are open-sourced under the Apache-2.0 license and we welcome community contributions. To learn more, see our [contributing guidelines](https://github.com/mongodb/awscdk-resources-mongodbatlas/blob/main/CONTRIBUTING.md). 

The fastest way to get started is to create a [MongoDB Atlas account from the AWS Marketplace](https://aws.amazon.com/marketplace/pp/prodview-pp445qepfdy34). Go build with MongoDB Atlas and the AWS CDK today!

Learn how to quickly and easily deploy a MongoDB Atlas instance using AWS CDK with TypeScript.

Zuhair Ahmed

Content by Zuhair Ahmed

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

How to Get Started with MongoDB Atlas Stream Processing and the HashiCorp Terraform MongoDB Atlas Provider

Leveraging Atlas Vector Search With HashiCorp Terraform: Empowering Semantic Search in Modern Applications

How to Deploy MongoDB Atlas with Terraform on AWS

How to Deploy MongoDB Atlas with AWS CDK in TypeScript