> This page location: /docs.md > /docs/management.md

> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

# 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.](https://www.mongodb.com/docs/atlas/tutorial/major-version-change.md#std-label-upgrade-major-MongoDB-version)

Once you have configured a test environment, continue to experiment with a Terraform-managed infrastructure with [additional resources](https://www.mongodb.com/docs/atlas/terraform.md#std-label-additional-resources-atlas-terraform) from MongoDB and HashiCorp.

Atlas Infinite clusters support the Atlas Terraform provider. To learn more, see [Create an Atlas Infinite cluster with Terraform](https://www.mongodb.com/docs/atlas/terraform.md#std-label-terraform-create-infinite-cluster) and [MongoDB Atlas Infinite: Overview.](https://www.mongodb.com/docs/atlas/infinite/atlas-infinite-landing.md#std-label-atlas-infinite-edition)

## Prerequisites

Before deploying MongoDB Atlas with Terraform, you must:

- Create an Atlas [account.](https://www.mongodb.com/docs/atlas/tutorial/create-atlas-account.md#std-label-create-atlas-account)

- Obtain your [Organization ID](https://www.mongodb.com/docs/atlas/access/orgs-create-view-edit-delete.md#std-label-create-organization) of which you are the [`Organization Owner`.](https://www.mongodb.com/docs/atlas/reference/user-roles.md#mongodb-authrole-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](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/guides/provider-configuration#service-account-recommended). 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.](https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli)

## Deploy MongoDB Atlas with Terraform

1. Create and navigate to an empty directory.

   ```sh
   mkdir terraform-proj
   cd terraform-proj
   ```

2. Create your terraform files.

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

   ```sh
   touch main.tf provider.tf variables.tf versions.tf
   ```

3. Populate supporting files.

   Add the following content to `provider.tf`:

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

   Add the following content to `variables.tf`:

   ```terraform
   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
   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.](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs#environment-variables)

4. Configure `main.tf` contents.

   **Note:**

   The following example uses the [project module](https://registry.terraform.io/modules/terraform-mongodbatlas-modules/project/mongodbatlas/latest) to create the project, and the [mongodbatlas\_advanced\_cluster](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/resources/advanced_cluster) resource to create a Free cluster.

   Add the following content to your `main.tf` file:

   ```terraform
   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](https://www.mongodb.com/docs/atlas/cloud-providers-regions.md#std-label-create-cluster-cloud-provider-region) 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.](https://www.mongodb.com/docs/atlas/terraform.md#std-label-terraform-create-infinite-cluster)

5. (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.

6. Initialize your project.

   To initialize your project, run the following command:

   ```sh
   terraform init
   ```

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

7. View your execution plan.

   To view your execution plan, run the following command:

   ```sh
   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.

8. Deploy your infrastructure.

   To deploy your infrastructure, run the following command:

   ```sh
   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:

```terraform
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.](https://www.mongodb.com/docs/atlas/infinite/atlas-infinite-landing.md#std-label-atlas-infinite-not-supported)

- **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 (Amazon Web Services) Gen2 hardware, so append `_GEN_2` to the tier name, as in `M60_GEN_2`. To learn more, see [Gen2 Dedicated Clusters.](https://www.mongodb.com/docs/atlas/manage-clusters.md#std-label-gen2-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.](https://www.mongodb.com/docs/atlas/infinite/atlas-infinite-architecture.md#std-label-atlas-infinite-replication)

- **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.](https://www.mongodb.com/docs/atlas/cluster-config/multi-cloud-distribution.md#std-label-atlas-infinite-workload-isolation)

- **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.](https://www.mongodb.com/docs/atlas/infinite/atlas-infinite-storage.md#std-label-atlas-infinite-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.](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/resources/advanced_cluster)

## 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:

```text
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](https://registry.terraform.io/modules/terraform-mongodbatlas-modules/cluster/mongodbatlas/latest) and the [Atlas Terraform Provider documentation](https://github.com//mongodb/terraform-provider-mongodbatlas/blob/master/README.md) for more complete configurations.

- **Connect to the cluster**: Use the connection string from the cluster object or from your Terraform output values.

Additional resources:

- [Atlas documentation](https://www.mongodb.com/docs/atlas/index.md#std-label-atlas-index)

- [Atlas Terraform Provider GitHub documentation](https://github.com//mongodb/terraform-provider-mongodbatlas/blob/master/README.md)

- [Terraform documentation](https://developer.hashicorp.com/terraform/docs)
