Get Started with Terraform and the MongoDB Atlas Provider

You can use Terraform to manage your MongoDB Atlas infrastructure as code with the Atlas Terraform provider. The Atlas Terraform provider automates infrastructure deployments by simplifying the process to provision, manage, and control Atlas infrastructure as code.

This guide teaches you how to create and destroy Atlas clusters in an existing MongoDB Atlas organization.

Note

The Atlas Terraform provider supports any MongoDB version that Atlas supports in your project and region. To learn how to change your cluster's MongoDB version, see Upgrade a major version.

Once you have configured a test environment, continue to experiment with a Terraform-managed infrastructure with additional resources from MongoDB and HashiCorp.

Atlas Infinite clusters support the Atlas Terraform provider. To learn more, see Create an Atlas Infinite cluster with Terraform and MongoDB Atlas Infinite: Overview.

Prerequisites

Before deploying MongoDB Atlas with Terraform, you must:

Create an Atlas account.
Obtain your Organization ID of which you are the Organization Owner.

Tip
You can find your Organization ID in the Atlas UI, under your organization's General Settings.
Configure a Service Account (SA) Authentication. The Organization Owner role is required to view the Organization ID, manage service accounts, and create or delete clusters and other project resources.
Install Terraform.

Deploy MongoDB Atlas with Terraform

Create and navigate to an empty directory.

mkdir terraform-proj
cd terraform-proj

Create your terraform files.

Create the main.tf, provider.tf, variables.tf, and versions.tf files.

touch main.tf provider.tf variables.tf versions.tf

Populate supporting files.

Add the following content to provider.tf:

provider "mongodbatlas" {
  client_id     = var.client_id
  client_secret = var.client_secret
}

Add the following content to variables.tf:

variable "client_id" {
  description = "Atlas Service Account client ID"
  type        = string
}
variable "client_secret" {
  description = "Atlas Service Account client secret"
  type        = string
  sensitive   = true
}
variable "org_id" {
  description = "Atlas organization ID"
  type        = string
}

Add the following content to versions.tf:

terraform {
  required_providers {
    mongodbatlas = {
      source  = "mongodb/mongodbatlas"
      version = "~> 2.2"
    }
  }
  required_version = "~> 1.0"
}

Note

Your Atlas Service Account client ID and client secret are secrets. Consider storing them as environment variables.

Configure `main.tf` contents.

Note

The following example uses the project module to create the project, and the mongodbatlas_advanced_cluster resource to create a Free cluster.

Add the following content to your main.tf file:

module "project" {
  source = "terraform-mongodbatlas-modules/project/mongodbatlas"
  name   = "tenant-example-project"
  org_id = var.org_id
}
resource "mongodbatlas_advanced_cluster" "this" {
  project_id   = module.project.id
  name         = "TenantCluster"
  cluster_type = "REPLICASET"
  replication_specs = [
    {
      region_configs = [
        {
          provider_name         = "TENANT"
          backing_provider_name = "AWS"
          region_name           = "US_EAST_1"
          priority              = 7
          electable_specs = {
            instance_size = "M0"
          }
        }
      ]
    }
  ]
}

If you work with a different cloud provider or region, you can update the following fields to match your environment.

Field	New Value
`backing_provider_name`	Your provider. Possible values are: `"AWS"`, `"AZURE"`, or `"GCP"`.
`region_name`	See Cloud Providers and Regions for all the regions you can use.

Important

You can set database_edition on the mongodbatlas_advanced_cluster resource when you create a dedicated cluster. You can't change it afterward, and you can't scale a dedicated cluster back to a Free or Flex cluster. database_edition is unavailable for Free clusters, such as the M0 cluster in this example, and for Flex clusters.

The mongodbatlas_advanced_cluster resource, and both the singular (mongodbatlas_advanced_cluster) and plural (mongodbatlas_advanced_clusters) data sources, expose database_edition and the read-only effective_database_edition attribute. Because database_edition is optional, use effective_database_edition to confirm which edition Atlas assigned, even if you didn't set it yourself.

To create a dedicated Atlas Infinite cluster, see Create an Atlas Infinite cluster with Terraform.

(Optional) Display parameters.

You can output information from your Terraform configuration to your terminal window. This is useful for values you won't know until Atlas creates the resources, such as your connection string.

If you want to display your parameters after you deploy your project, add some output lines of code to your main.tf file.

Initialize your project.

To initialize your project, run the following command:

terraform init

This command also downloads and installs the MongoDB Atlas Provider, if you haven't already.

View your execution plan.

To view your execution plan, run the following command:

terraform plan

Terraform details the changes that it plans to make. If the output is not what you expect, then there might be an issue in your main.tf file.

Deploy your infrastructure.

To deploy your infrastructure, run the following command:

terraform apply

When prompted Do you want to perform these actions?, enter yes.

Note

New Atlas resources can take a few minutes to provision. The Atlas Terraform provider updates you every ten seconds until it's complete.

Create an Atlas Infinite cluster with Terraform

The following example uses Terraform to create an Atlas Infinite cluster with compute auto-scaling enabled:

resource "mongodbatlas_advanced_cluster" "infinite" {
  project_id       = module.project.id
  name             = "InfiniteCluster"
  cluster_type     = "REPLICASET"
  database_edition = "INFINITE"
  replication_specs = [
    {
      region_configs = [
        {
          provider_name = "AWS"
          priority      = 7
          region_name   = "US_EAST_1"
          electable_specs = {
            instance_size = "M10"
            node_count    = 2
          }
          auto_scaling = {
            compute_enabled           = true
            compute_max_instance_size = "M60_GEN_2"
            storage_config = {
              shard_size_limit_gb = 10240
            }
          }
        }
      ]
    }
  ]
}

When you create an Atlas Infinite cluster with Terraform, the following requirements and limitations apply:

Required settings: Set database_edition to "INFINITE" on the mongodbatlas_advanced_cluster resource, and set an explicit compute_enabled value (true or false) under auto_scaling. Atlas requires this value at cluster creation.
Immutable database edition: You can't change the database edition of a cluster after you create it.
Public preview limitations: All other Atlas Infinite public preview limitations apply to clusters that you deploy with Terraform. To learn more, see Not Supported in Public Preview.
Cluster type: Dedicated Atlas Infinite clusters support the REPLICASET cluster type only.
Auto-scaling maximum tier: compute_max_instance_size is required when compute_enabled is true. Atlas Infinite clusters at the M30 tier and larger run on AWS Gen2 hardware, so append _GEN_2 to the tier name, as in M60_GEN_2. To learn more, see Gen2 Dedicated Clusters.
Electable nodes: An Atlas Infinite cluster has two electable compute nodes, a primary and a standby, so set node_count to 2. To learn more, see Replication and Failover.
Read-only and analytics nodes: To serve more reads or to isolate analytics queries from your operational workload, set read_only_specs or analytics_specs alongside electable_specs in the same region_configs object. To learn more, see Workload Isolation on Atlas Infinite clusters.
Storage limit: storage_config.shard_size_limit_gb is required only if you include storage_config. If you omit storage_config, Atlas applies the default maximum storage limit. To learn more, see Max Storage Limit.

Note

storage_config.shard_size_limit_gb sets the maximum amount of data the cluster can store. To learn more, see the Terraform provider documentation.

Verify the Deployment

After terraform apply completes, confirm the cluster is deployed.

A new cluster appears in the Atlas UI under your project.
If you added output values to main.tf, the connection string appears in the Terraform output.

Terminate MongoDB Atlas Instance

To delete all of the resources created in your Terraform directory, run the following command:

terraform destroy

Warning

If you delete all your resources, you can't recover them.

When prompted Do you really want to destroy all resources?, enter yes.

Next Steps

After you deploy your cluster, you can:

Scale to a dedicated cluster: Review the cluster module and the Atlas Terraform Provider documentation for more complete configurations.
Connect to the cluster: Use the connection string from the cluster object or from your Terraform output values.

Additional resources:

Back

Overview

Terraform Modules

Get Started with Terraform and the MongoDB Atlas Provider

Prerequisites

Deploy MongoDB Atlas with Terraform

Create and navigate to an empty directory.

Create your terraform files.

Populate supporting files.

Configure main.tf contents.

(Optional) Display parameters.

Initialize your project.

View your execution plan.

Deploy your infrastructure.

Create an Atlas Infinite cluster with Terraform

Verify the Deployment

Terminate MongoDB Atlas Instance

Next Steps

Configure `main.tf` contents.