Create an Atlas Cluster from a Template using Terraform

This page outlines how to use the Atlas template for Terraform files included with the MongoDB Extension for Visual Studio Code to create Flex clusters.

After loading the template, you configure the cluster and provide details about your Atlas account. You then use Terraform commands to plan, apply, and destroy your Atlas cluster.

Prerequisites

Before you use the Atlas template for Terraform files included with the MongoDB Extension for Visual Studio Code, you must:

Install MongoDB for VS Code Extension
Install Terraform
Have an Atlas account.
Have an Atlas organization.
Have a service account in an |service| organization with the Organization Owner or Organization Project Creator role.

Procedures

Create an Atlas Terraform File using the Template

Use the Atlas template for Terraform files included with the VS Code Extension to configure an Atlas cluster:

In Visual Studio Code, create a new file.

Operating System	Method	Actions
Any	Visual Studio Code Menu	File > New File
MacOS	Keyboard Shortcut	Press `Command` + `N`
Windows and Linux	Keyboard Shortcut	Press `Control` + `N`

Save the file. Name it `main.tf`.

Note

main.tf is the recommended filename for the entry point to a Terraform module.

In the `main.tf` file, type `atlas`, then press the Enter or Return key.

The MongoDB Extension for VSCode populates the file with an example configuration using the MongoDB Atlas Terraform provider to create a Flex cluster.

Update the Atlas Terraform configuration to configure your cluster.

The cursor moves to select the value of the name argument of the mongodbatlas_project resource.

Provide values for the following arguments to configure your cluster:

Tip

Press the Tab key to select to the next argument in the template that you should update.

Attribute	Value
`mongodbatlas_project` `.name`	Name of the Atlas project that this configuration creates.
`mongodbatlas_advanced_cluster` `.name`	Name of the Atlas Flex cluster that this configuration creates.
`mongodbatlas_advanced_cluster` `.replication_specs.` `region_configs.` `backing_provider_name`	Provider on which the Atlas Flex cluster that this configuration creates is hosted. Choose one of the following accepted values: `AWS` `AZURE` `GCP`
`mongodbatlas_advanced_cluster` `.replication_specs.` `region_configs.` `region_name`	Region to which the Atlas Flex cluster that this configuration creates is deployed. Ensure that the region you chose supports Flex clusters. For details about the regions that each provider supports, see the following sections in the Atlas documentation: Amazon Web Services Google Cloud Platform Microsoft Azure

Update the `local` variables.

Warning

The local variables contain sensitive information. Do not check these values in to a repository that is available publicly.

Provide values for the following local variables:

Variable	Value
`mongodb_atlas_client_id`	Atlas service account client ID.
`mongodb_atlas_client_secret`	Atlas service account client secret.
`mongodb_atlas_org_id`	Atlas organization ID in which you want to create a project.
`mongodb_atlas_database_username`	Username of the MongoDB database user that Atlas creates for your cluster.
`mongodb_atlas_database_user_password`	Password for the MongoDB database user named in `mongodb_atlas_database_username`.
`mongodb_atlas_accesslistip`	IP address or CIDR block from which your Atlas cluster is accessible.

Note

The template authenticates to Atlas with a service account. API keys are also supported, but service accounts are the recommended authentication method. To learn about both methods, see the MongoDB Atlas Terraform Provider authentication guide.

Example

Use an Input Variables File to Maximize security

To maximize security, consider taking the following steps:

Define the local variables in an input variables file.
variable "mongodb_atlas_client_id" { default = "my-client-id" } variable "mongodb_atlas_client_secret" { default = "my-client-secret" }
Exclude the input variables file from your repository. For example, add the filename to the .gitignore file for your repository.
Reference variables from the input variables file in the main.tf file by prefacing them with var..
provider "mongodbatlas" { client_id = var.mongodb_atlas_client_id client_secret = var.mongodb_atlas_client_secret }

Add optional configuration options to the `main.tf` file.

For a complete list of supported configuration options, see the MongoDB Atlas Terraform Provider documentation.

For production deployments, consider the official MongoDB Atlas Cluster module, which bundles the cluster resource with production best-practice defaults.

Note

Flex clusters don't support all configurations available with the MongoDB Atlas Terraform provider. For a list of unsupported configurations, see the Atlas documentation.

Save the `main.tf` file.

Create the Atlas Cluster using Terraform

After you create a Terraform file using the template, create the Atlas cluster:

Navigate to the directory in which you saved your `main.tf` file.

Run the `terraform init` command to install the required providers.

The following output indicates that the MongoDB Atlas Terraform Provider is installed and ready for use:

terraform init

Initializing the backend...
Initializing provider plugins...
- Finding mongodb/mongodbatlas versions matching "~> 2.0"...
- Installing mongodb/mongodbatlas v2.18.0...
- Installed mongodb/mongodbatlas v2.18.0 (signed by a HashiCorp partner, key ID 2A32ED1F3AD25ABF)
Partner and community providers are signed by their developers.
If you'd like to know more about provider signing, you can read about it here:
https://developer.hashicorp.com/terraform/cli/plugins/signing
Terraform has created a lock file .terraform.lock.hcl to record the provider
selections it made above. Include this file in your version control repository
so Terraform can guarantee to make the same selections by default when you run
"terraform init" in the future.
Terraform has been successfully initialized!
You may now begin working with Terraform. Try running "terraform plan" to see
any changes that are required for your infrastructure. All Terraform commands
should now work.
If you ever set or change modules or backend configuration, rerun this command
to reinitialize your working directory. If you forget, other commands will
detect it and remind you to do so if necessary.

Run the `terraform plan` command to view what happens when you apply the configuration.

The following output shows what happens when you apply the Terraform configuration:

terraform plan

Terraform used the selected providers to generate the following execution
plan. Resource actions are indicated with the following symbols:
  + create
Terraform will perform the following actions:
  # mongodbatlas_advanced_cluster.my_cluster will be created
  + resource "mongodbatlas_advanced_cluster" "my_cluster" {
      + advanced_configuration                                 = (known after apply)
      + backup_enabled                                         = (known after apply)
      + bi_connector_config                                    = (known after apply)
      + cluster_id                                             = (known after apply)
      + cluster_type                                           = "REPLICASET"
      + config_server_management_mode                          = (known after apply)
      + config_server_type                                     = (known after apply)
      + connection_strings                                     = (known after apply)
      + create_date                                            = (known after apply)
      + delete_on_create_timeout                               = true
      + encryption_at_rest_provider                           = (known after apply)
      + global_cluster_self_managed_sharding                   = (known after apply)
      + mongo_db_major_version                                 = (known after apply)
      + mongo_db_version                                       = (known after apply)
      + name                                                   = "atlasClusterName"
      + paused                                                 = (known after apply)
      + pit_enabled                                           = (known after apply)
      + project_id                                             = (known after apply)
      + redact_client_log_data                                 = (known after apply)
      + replica_set_scaling_strategy                           = (known after apply)
      + replication_specs                                      = [
          + {
              + container_id   = (known after apply)
              + external_id    = (known after apply)
              + region_configs = [
                  + {
                      + analytics_auto_scaling = (known after apply)
                      + analytics_specs        = (known after apply)
                      + auto_scaling           = (known after apply)
                      + backing_provider_name  = "AWS"
                      + electable_specs        = (known after apply)
                      + priority               = 7
                      + provider_name          = "FLEX"
                      + read_only_specs        = (known after apply)
                      + region_name            = "US_EAST_1"
                    },
                ]
              + zone_id        = (known after apply)
              + zone_name      = (known after apply)
            },
        ]
      + root_cert_type                                         = (known after apply)
      + state_name                                             = (known after apply)
      + termination_protection_enabled                         = (known after apply)
      + use_aws_time_based_snapshot_copy_for_fast_initial_sync = (known after apply)
      + version_release_system                                 = (known after apply)
    }
  # mongodbatlas_database_user.my_user will be created
  + resource "mongodbatlas_database_user" "my_user" {
      + auth_database_name = "admin"
      + aws_iam_type       = "NONE"
      + id                 = (known after apply)
      + ldap_auth_type     = "NONE"
      + oidc_auth_type     = "NONE"
      + password           = (sensitive value)
      + password_wo        = (write-only attribute)
      + project_id         = (known after apply)
      + username           = "myUser"
      + x509_type          = "NONE"
      + roles {
          + database_name = "admin"
          + role_name     = "atlasAdmin"
        }
    }
  # mongodbatlas_project.my_project will be created
  + resource "mongodbatlas_project" "my_project" {
      + cluster_count                                           = (known after apply)
      + created                                                 = (known after apply)
      + id                                                      = (known after apply)
      + ip_addresses                                            = (known after apply)
      + is_cluster_ai_assistant_enabled                         = (known after apply)
      + is_collect_database_specifics_statistics_enabled        = (known after apply)
      + is_data_explorer_enabled                                = (known after apply)
      + is_data_explorer_gen_ai_features_enabled                = (known after apply)
      + is_data_explorer_gen_ai_sample_document_passing_enabled = (known after apply)
      + is_extended_storage_sizes_enabled                       = (known after apply)
      + is_native_reranking_enabled                             = (known after apply)
      + is_performance_advisor_enabled                          = (known after apply)
      + is_realtime_performance_panel_enabled                   = (known after apply)
      + is_schema_advisor_enabled                               = (known after apply)
      + is_slow_operation_thresholding_enabled                  = (known after apply)
      + name                                                    = "atlasProjectName"
      + org_id                                                  = "5d3716bfcf09a21576d7983e"
      + region_usage_restrictions                               = (known after apply)
      + with_default_alerts_settings                            = true
    }
  # mongodbatlas_project_ip_access_list.my_ipaddress will be created
  + resource "mongodbatlas_project_ip_access_list" "my_ipaddress" {
      + aws_security_group = (known after apply)
      + cidr_block         = (known after apply)
      + comment            = "My IP Address"
      + id                 = (known after apply)
      + ip_address         = "203.0.113.10"
      + project_id         = (known after apply)
    }
Plan: 4 to add, 0 to change, 0 to destroy.
Changes to Outputs:
  + connection_strings = (known after apply)
─────────────────────────────────────────────────────────────────────────────
Note: You didn't use the -out option to save this plan, so Terraform can't
guarantee to take exactly these actions if you run "terraform apply" now.

Proceed to the next step if the information is correct.

Run the `terraform apply` command to create an Atlas cluster from the Terraform configuration.

Type yes when prompted to confirm that you want to apply the configuration.

Note

The terraform apply command might take several minutes to complete.

The following output indicates that your Atlas cluster is created. You can create a connection to this deployment using the VS Code Extension with the displayed connection string:

terraform apply

Apply complete! Resources: 4 added, 0 changed, 0 destroyed.
Outputs:
connection_strings = "mongodb+srv://atlasClusterName.xxxxx.mongodb.net"

Delete the Atlas Cluster using Terraform

Warning

Deleting a cluster destroys databases, collections, and documents stored on it and all other resources defined in the Terraform configuration in which you configured the cluster.

Proceed with caution.

To delete the Atlas cluster:

Navigate to the directory in which you saved your `main.tf` file.

Run the `terraform destroy` command to delete the resources defined in the configuration.

terraform destroy

Type yes when prompted to confirm that you want to destroy the resources defined in the configuration.

Note

The terraform destroy command might take several minutes to complete.

The following output indicates that the Atlas cluster and all associated resources are deleted:

Destroy complete! Resources: 4 destroyed.

Back

AI & Data Usage

Commands

Create an Atlas Cluster from a Template using Terraform

Prerequisites

Procedures

Create an Atlas Terraform File using the Template

In Visual Studio Code, create a new file.

Save the file. Name it main.tf.

In the main.tf file, type atlas, then press the Enter or Return key.

Update the Atlas Terraform configuration to configure your cluster.

Update the local variables.

Add optional configuration options to the main.tf file.

Save the main.tf file.

Create the Atlas Cluster using Terraform

Navigate to the directory in which you saved your main.tf file.

Run the terraform init command to install the required providers.

Run the terraform plan command to view what happens when you apply the configuration.

Run the terraform apply command to create an Atlas cluster from the Terraform configuration.

Delete the Atlas Cluster using Terraform

Navigate to the directory in which you saved your main.tf file.

Run the terraform destroy command to delete the resources defined in the configuration.

Save the file. Name it `main.tf`.

In the `main.tf` file, type `atlas`, then press the Enter or Return key.

Update the `local` variables.

Add optional configuration options to the `main.tf` file.

Save the `main.tf` file.

Navigate to the directory in which you saved your `main.tf` file.

Run the `terraform init` command to install the required providers.

Run the `terraform plan` command to view what happens when you apply the configuration.

Run the `terraform apply` command to create an Atlas cluster from the Terraform configuration.

Navigate to the directory in which you saved your `main.tf` file.

Run the `terraform destroy` command to delete the resources defined in the configuration.