Community

Karen Zhang

Community author




[MongoDB Atlas](https://www.mongodb.com/docs/atlas/getting-started/) is a fully managed cloud database. It handles the tricky parts of setting up, managing, and fixing your MongoDB databases on any major cloud platform (like AWS, Azure, or GCP). It's the easiest way to get started, run, and grow your MongoDB databases in the cloud.

[Terraform](https://developer.hashicorp.com/terraform/docs) is an open-source infrastructure as code (IaC) tool used to manage and provision infrastructure across various platforms, including cloud providers and on-premise data centers. Terraform automates your infrastructure's creation, modification, and destruction, ensuring consistency and repeatability. Terraform has a [MongoDB Atlas provider](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs) that interacts with the resources supported by [MongoDB Atlas](https://www.mongodb.com/cloud/atlas).

In this tutorial, we’ll guide you through setting up MongoDB Atlas on the Azure platform and utilizing Terraform for deployment. The source code used in this article can be found in the [GitHub repository](https://github.com/Karenzhang7717/mongodb-atlas-deployment-to-azure/tree/main).

## Prerequisites

Before we get started, you will need to have the following accounts/tools set up:

- A MongoDB Atlas account — register to get your free [MongoDB Atlas account](https://www.mongodb.com/cloud/atlas/register).
- An Azure account — register to get your free [Azure account](https://azure.microsoft.com/en-ca/free).
- Terraform — you can follow HashiCorp Terrform’s [download page](https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli).

## Setting up the environment

To set up the environment, we will first generate MongoDB Atlas API access key, and then set up a billing method.

### Generate MongoDB Atlas API access keys

After establishing an account on MongoDB Atlas and logging in, the next step is to generate an API key to verify the Terraform MongoDB Atlas Provider. To do this, select the access manager for the organization and create the access key. Follow the documentation to learn more about [creating an API key](https://www.mongodb.com/docs/atlas/configure-api-access/).

![Capture where to create an API key(screenshot from the Atlas UI representing the Organization Access Manager section)](https://images.contentstack.io/v3/assets/blt39790b633ee0d5a7/blt5452368b91040458/6671609976906dde1a9ee7ab/image6.png)

*Capture where to create an API key* *(screenshot from the Atlas UI representing the Organization Access Manager section)*

Give your API key a clear name that reflects its purpose, like “Terraform Deployment API Key.” Next, we’ll choose the permissions needed for your Terraform tasks. Both *Organization Owner* and *Organization Project Creator* roles allow for enough access to complete this, but the *Organization Project Creator* role should be chosen following the principle of least privilege. To learn more about the user roles, follow the [Organization Roles and Project Roles](https://www.mongodb.com/docs/atlas/reference/user-roles/).

![Capture for generating an API key* (screenshot from the Atlas UI representing creating API key section)](https://images.contentstack.io/v3/assets/blt39790b633ee0d5a7/bltab46fbe3c01b2091/667160987ef09ee2abf3fcc4/image4.png "Capture for generating an API key* (screenshot from the Atlas UI representing creating API key section)")

Copy your private key and public key, then set up the environment variables:

``` bash
export MONGODB_ATLAS_PUBLIC_KEY="<insert your public key here>"
export MONGODB_ATLAS_PRIVATE_KEY="<insert your private key here>"
```

*Capture for adding current IP to Access List Entry* *(screenshot from the Atlas UI representing adding access list entry section)*

Next, we will add an API key access list entry to ensure that API calls originating from IPs or CIDR ranges can give access. We use our current IP address and save.

### Setting up a billing method

MongoDB allows a free M0 cluster tier that you do not have to pay for. However, if you want to deploy any other clusters, we will have to set up a billing method. Follow the documentation about setting up a [billing](https://www.mongodb.com/docs/atlas/billing/) method.

## Creating Terraform configuration files — variables.tf, terraform.tfvars, and main.tf files

We are now going to create a `variables.tf` file for declaring Terraform variables, a `terraform.tfvars` file for defining variable values and secrets, and a `main.tf` for the main Terraform configuration. In Terraform, these configuration files (`variables.tf`, `terraform.tfvars`, and `main.tf`) are typically created within the root directory of your Terraform project. You can find the source code in the [GitHub repository](https://github.com/Karenzhang7717/mongodb-atlas-deployment-to-azure/tree/main).

First, we define the MongoDB Atlas and Azure Providers in `main.tf`:

``` bash
# Define the MongoDB Atlas and Azure Providers
terraform {
  required_providers {
    mongodbatlas = {
      source = "mongodb/mongodbatlas"
      version = "=1.16.0"
    }
    azurerm = {
      source  = "hashicorp/azurerm"
      version = "=3.0.0"
    }
  }
}
Then, we start defining all the variables our configuration will use in the variables.tf file.
```

The code block below defines the variables used. Variables include identifiers for the project and environment, the size of the computing resources allocated, the cloud platform to use (AWS, GCP, Azure), the specific region within that platform, the desired version of MongoDB, and the IP address(es) allowed to access the database cluster.

``` bash
# Atlas Organization ID
variable "atlas_org_id" {
 type        = string
 description = "Atlas Organization ID"
}
# Atlas Project Name
variable "atlas_project_name" {
 type        = string
 description = "Atlas Project Name"
}
# Atlas Project Environment
 variable "environment" {
   type        = string
   description = "The environment to be built"
 }
# Cluster Instance Size Name
variable "cluster_instance_size_name" {
 type        = string
 description = "Cluster instance size name"
}
# Cloud Provider to Host Atlas Cluster
variable "cloud_provider" {
 type        = string
 description = "AWS or GCP or Azure"
}
# Atlas Region
variable "atlas_region" {
 type        = string
 description = "Atlas region where resources will be created"
}
# MongoDB Version
variable "mongodb_version" {
 type        = string
 description = "MongoDB Version"
}
# IP Address Access
variable "ip_address" {
 type = string
 description = "IP address used to access Atlas cluster"
}
```

In the `terraform.tfvars` file, we specify the use of MongoDB version 7.0, a M10-sized cluster in the US_EAST_2 region on Azure. If you are outside North America, you can refer to the regions supported following the documentation for [Microsoft Azure](https://www.mongodb.com/docs/atlas/reference/microsoft-azure/#std-label-microsoft-azure).

Please note that Atlas supports specific Azure regions and availability zones, and some regions do not support free clusters (M0) and shared clusters (M2/M5).

``` bash
atlas_org_id = "<UPDATE WITH YOUR ORG ID>"
atlas_project_name = "yourProjectName"
environment = "dev"
cluster_instance_size_name = "M10"
cloud_provider = "Azure"
atlas_region = "US_EAST_2"
mongodb_version = "7.0"
ip_address = "<UPDATE WITH YOUR IP>"
```

## Configuring a MongoDB Atlas project

To create a project using Terraform, we will need the **MongoDB Atlas Organization ID** with at least the Organization Project Creator role. To get this information, we can go to *Settings* on the left-hand side menu bar in the UI, and we can find *Organization Settings* with the *Organization ID*. Please refer to the documentation on [Organizations](https://www.mongodb.com/docs/cloud-manager/tutorial/manage-organizations/) for further reference.

So next, in our `main.tf`file, we will use the mongodbatlas_project resource from Terraform MongoDB Atlas Provider to create our project. We add this to `main.tf`:

``` bash
# Create a Project
resource "mongodbatlas_project" "atlas-project" {
 org_id = var.atlas_org_id
 name = var.atlas_project_name
}
```

## Creating a MongoDB Atlas user, password, and IP access list

We must add a corresponding database user to our MongoDB Atlas project. Refer to the documentation for available [user roles](https://www.mongodb.com/docs/atlas/reference/api-resources-spec/v2/#operation/createOneDatabaseUserInOneProject) in case you want to customize the user’s Role-Based Access Control.

The code block below creates a database user with a random password, and to review the password, you will need to put the `terraform output -json user_password` command in your terminal.

``` bash
# Create a Database User
resource "mongodbatlas_database_user" "db-user" {
 username = "user-1"
 password = random_password.db-user-password.result
 project_id = mongodbatlas_project.atlas-project.id
 auth_database_name = "admin"
 roles {
   role_name     = "readWrite"
   database_name = "${var.atlas_project_name}-db"
 }
}
# Create a Database Password
resource "random_password" "db-user-password" {
 length = 16
 special = true
 override_special = "_%@"
}
Next, we need to create the IP access list.

# Create Database IP Access List
resource "mongodbatlas_project_ip_access_list" "ip" {
 project_id = mongodbatlas_project.atlas-project.id
 ip_address = var.ip_address
}
We will need to put the IP address that we are connecting to the MongoDB Atlas cluster into the terraform.tfvars file.
```

## Provisioning the MongoDB Atlas cluster

We will now use the [`mongodbatlas_cluster`](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/resources/cluster)[ resource](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/resources/cluster) to create a MongoDB Atlas cluster. The resource lets you create, edit, and delete clusters.

``` bash
resource "mongodbatlas_cluster" "test" {
 project_id   = mongodbatlas_project.atlas-project.id
 name         = "${var.atlas_project_name}-${var.environment}-cluster"
 cluster_type = "REPLICASET"
 replication_specs {
   num_shards = 1
   regions_config {
     region_name     = var.atlas_region
     electable_nodes = 3
     priority        = 7
     read_only_nodes = 0
   }
 }
 cloud_backup     = true
 auto_scaling_disk_gb_enabled = true
 mongo_db_major_version       = "7.0"
 # Provider Settings "block"
 provider_name               = var.cloud_provider
 provider_disk_type_name     = "P6"
 provider_instance_size_name = var.cluster_instance_size_name
}
```

The code block shown above specifies a cluster named “test” with a replica set deployment type, which is ideal for applications requiring high availability and data redundancy.

The cluster is configured with a single shard and is set to automatically scale its disk storage as needed. The naming convention for the cluster incorporates variables that allow for environment-specific customization, such as `${var.atlas_project_name}-${var.environment}-cluster`.

The configuration also specifies a replica set with three electable nodes in a configurable region, ensuring that the primary node can be effectively elected. The MongoDB major version is set to "7.0," aligning the cluster with the latest stable release.

## Defining Terraform outputs

You can display information from your Terraform setup directly onto the terminal when running Terraform commands. This feature is particularly handy for obtaining values that are only determined after the resources have been created, such as a randomly generated database user password or the connection string needed for your Atlas cluster. The following code is in your `main.tf` file and will ensure that these values are shown on the terminal once Terraform has finished executing.

``` bash
output "cluster_name" {
 value = mongodbatlas_cluster.test.name
 description = "Name of the MongoDB Atlas cluster"
}
output "cluster_uri" {
 value = "mongodb://user-1:${random_password.db-user-password.result}@${mongodbatlas_cluster.test.name}.mongodb.net:27017/?authSource=admin&replicaSet=test-replicaSet"
 description = "Connection URI for the MongoDB Atlas cluster"
 sensitive = true
}
output "project_id" {
 value = mongodbatlas_cluster.test.project_id
 description = "ID of the MongoDB Atlas project where the cluster resides"
}
Initializing Terraform
```

We are now ready to run `terraform init`. This command will initialize Terraform and download Terraform Azure and MongoDB Atlas providers.

![Capture for running Terraform Init](https://images.contentstack.io/v3/assets/blt39790b633ee0d5a7/blt6af9c154669614df/667160980c0c3ee33e0391e6/image2.png "Capture for running Terraform Init")

The screenshot above shows that Terraform has been successfully initialized.

## Reviewing proposed Terraform deployment

Next, we will be using `terraform plan` to review the proposed changes.

![Capture for running Terraform Plan](https://images.contentstack.io/v3/assets/blt39790b633ee0d5a7/blt3faae720c17962e3/66716099b00d393d6de01406/image7.png "Capture for running Terraform Plan")



The screenshot above shows that Terraform will perform the following updates.

![Capture the results of running the Terraform Plan](https://images.contentstack.io/v3/assets/blt39790b633ee0d5a7/blt014ed6487ca02eb3/667160987b258dad25c8a8f6/image3.png "Capture the results of running the Terraform Plan")



It shows that Terraform will create the following five resources: including mongodbatlas_cluster.test, mongodbatlas_database_user.db-user, mongodbatlas_project.atlas-project, mongodbatlas_project_ip_access_list.ip, and random_password.db-user-password.

## Executing to create the resources

Now, we will execute the `terraform apply` command to initiate the deployment of the infrastructure. Upon reviewing and confirming that everything appears correct, respond with “yes” to give Terraform the go-ahead to proceed with the build.

![Screenshot representing terraform apply](https://images.contentstack.io/v3/assets/blt39790b633ee0d5a7/blt47a9479b3c624afc/667160981774d2e080a16bc3/image10.png "Screenshot representing terraform apply")

![Capture for running Terraform Apply](https://images.contentstack.io/v3/assets/blt39790b633ee0d5a7/blt4093cbe35078d82c/667160980c0c3e6e9d0391de/image1.png "Capture for running Terraform Apply")


It might take about 10 minutes for the cluster to deploy. Once it successfully deploys, you will be able to view it in Atlas UI. Below, we can see that an M10 cluster has been deployed to Azure in the East US 2 region.

![Capture for successfully deploying a cluster(screenshot from the Atlas UI representing the deployed cluster](https://images.contentstack.io/v3/assets/blt39790b633ee0d5a7/blt415ea215fbf51d60/66716099053191ea1d1f713e/image9.png "Capture for successfully deploying a cluster(screenshot from the Atlas UI representing the deployed cluster)")


Congratulations! You have now successfully deployed an M10 cluster to Azure.

## Cleaning up using Terraform destroy

When ready to destroy the infrastructure created, we can use `terraform destroy` to safely tear down the infrastructure. Type “yes” to destroy all the resources deployed. Be extra careful, though, if you are trying to destroy resources in the production environment.

![Capture for running Terraform Destroy](https://images.contentstack.io/v3/assets/blt39790b633ee0d5a7/blt6e78024cbb05ee84/66716099664d453b4e210f0d/image8.png "Capture for running Terraform Destroy")

## Conclusion

In this tutorial, we learned how to deploy a MongoDB Atlas cluster to Azure. The integration of MongoDB Atlas with Terraform on Azure offers a powerful and flexible approach to cloud database management. By leveraging Terraform’s infrastructure as code capabilities, we have streamlined the deployment process for MongoDB Atlas, ensuring that our infrastructure is both reproducible and easily manageable.


This tutorial will help you understand how to deploy Atlas cluster using Terraform. 

Karen Zhang

Content by Karen Zhang

Deploying MongoDB Atlas With Terraform with Azure