Navigation

    Create an Atlas Cluster from a Template using Terraform

    Preview

    MongoDB for VS Code is currently available as a Preview in the Visual Studio Marketplace. The product, its features, and the corresponding documentation may change during the Preview stage.

    This page outlines how to use the Atlas template for Terraform files included with the MongoDB Extension for Visual Studio Code to create Shared Tier Atlas 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:

    Procedures

    Create an Atlas Terraform File using the Template

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

    1

    In Visual Studio Code, create a new file.

    Operating SystemMethodActions
    AnyVisual Studio Code MenuFile > New File
    MacOSKeyboard ShortcutPress Command + N
    Windows and LinuxKeyboard ShortcutPress Control + N
    2

    Save the file. Name it main.tf.

    note

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

    3

    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 Shared Tier Atlas cluster.

    4

    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.

    AttributeValue
    mongodbatlas_project
    .name
    Name of the Atlas project that this configuration creates.
    mongodbatlas_cluster
    .name
    Name of the Atlas cluster that this configuration creates.
    mongodbatlas_cluster
    .backing_provider_name

    Provider on which the Atlas cluster that this configuration creates is hosted. Choose one of the following accepted values:

    • AWS
    • AZURE
    • GCP
    mongodbatlas_cluster
    .provider_region_name

    Region to which the Atlas cluster that this configuration creates is deployed. Ensure that the region you chose supports Atlas clusters of the instance size you want to deploy.

    By default the template provisions Shared Tier clusters: M2 and M5.

    For details about the instance sizes that each provider and region supports, see the following sections in the Atlas documentation:

    mongodbatlas_cluster
    .provider_instance_size_name

    Instance size of the Atlas cluster that this configuration creates.

    Either:

    • Choose one of the Shared Tier instance sizes included in the template: M2 or M5.
    • Enter another instance size that Atlas supports for your chosen provider and region.

    For details about the instance sizes that each provider and region supports, see the following sections in the Atlas documentation:

    mongodbatlas_cluster
    .disk_size_gbs

    Disk size of the Atlas cluster that this configuration creates. Ensure that you provide a value that is equal to or less than the maximum disk size for the instance size you chose.

    • For M2 clusters, enter 2.
    • For M5 clusters, enter 5.

    For details about the disk sizes that each provider supports for each instance size, see the following sections in the Atlas documentation:

    5

    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:

    VariableValue
    mongodb_atlas_api_pub_keyAtlas public API key.
    mongodb_atlas_api_pri_keyAtlas private API key.
    mongodb_atlas_org_idAtlas organization ID in which you want to create a project.
    mongodb_atlas_database_usernameUsername of the MongoDB database user that Atlas creates for your cluster.
    mongodb_atlas_database_user_passwordPassword for the MongoDB database user named in mongodb_atlas_database_username.
    mongodb_atlas_whitelistipIP address or CIDR block from which your Atlas cluster is accessible.

    Use an Input Variables File to Maximize security

    To maximize security, consider taking the following steps:

    1. Define the local variables in an input variables file.

      example

      variable "mongodb_atlas_api_pub_key" {
        default = "my-public-key"
      }
      
      variable "mongodb_atlas_api_pri_key" {
        default = "my-private-key"
      }
    2. Exclude the input variables file from your repository. For example, add the filename to the .gitignore file for your repository.
    3. Reference variables from the input variables file in the main.tf file by prefacing them with vars..

      example

      provider "mongodbatlas" {
        public_key  = vars.mongodb_atlas_api_pub_key
        private_key = vars.mongodb_atlas_api_pri_key
      }
    6

    Add optional configuration options to the main.tf file.

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

    note

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

    7

    Save the main.tf file.

    Create the Atlas Cluster using Terraform

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

    1
    2

    Run the terraform init command to install the required providers.

    terraform init

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

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    Initializing provider plugins... - Checking for available provider plugins... - Downloading plugin for provider "mongodbatlas" (terraform-providers/mongodbatlas) 0.5.1... The following providers do not have any version constraints in configuration, so the latest version was installed. To prevent automatic upgrades to new major versions that may contain breaking changes, it is recommended to add version = "..." constraints to the corresponding provider blocks in configuration, with the constraint strings suggested below. * provider.mongodbatlas: version = "~> 0.5" Terraform has been successfully initialized!
    3

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

    terraform plan

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

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    83
    84
    85
    86
    87
    88
    89
    90
    91
    92
    93
    94
    95
    96
    97
    98
    99
    100
    101
    102
    103
    104
    105
    106
    107
    108
    109
    110
    111
    112
    113
    114
    115
    The refreshed state will be used to calculate this plan, but will not be persisted to local or remote state storage. ------------------------------------------------------------------------ An execution plan has been generated and is shown below. Resource actions are indicated with the following symbols: + create Terraform will perform the following actions: # mongodbatlas_cluster.my_cluster will be created + resource "mongodbatlas_cluster" "my_cluster" { + advanced_configuration = (known after apply) + auto_scaling_disk_gb_enabled = false + backing_provider_name = "AWS" + backup_enabled = false + bi_connector = (known after apply) + cluster_id = (known after apply) + cluster_type = (known after apply) + connection_strings = (known after apply) + disk_size_gb = 2 + encryption_at_rest_provider = (known after apply) + id = (known after apply) + mongo_db_major_version = "4.2" + mongo_db_version = (known after apply) + mongo_uri = (known after apply) + mongo_uri_updated = (known after apply) + mongo_uri_with_options = (known after apply) + name = "atlasClusterName" + num_shards = 1 + paused = (known after apply) + pit_enabled = (known after apply) + project_id = (known after apply) + provider_backup_enabled = false + provider_disk_iops = (known after apply) + provider_disk_type_name = (known after apply) + provider_encrypt_ebs_volume = (known after apply) + provider_instance_size_name = "M2" + provider_name = "TENANT" + provider_region_name = "providerRegionName" + provider_volume_type = (known after apply) + replication_factor = (known after apply) + snapshot_backup_policy = (known after apply) + srv_address = (known after apply) + state_name = (known after apply) + labels { + key = (known after apply) + value = (known after apply) } + replication_specs { + id = (known after apply) + num_shards = (known after apply) + zone_name = (known after apply) + regions_config { + analytics_nodes = (known after apply) + electable_nodes = (known after apply) + priority = (known after apply) + read_only_nodes = (known after apply) + region_name = (known after apply) } } } # mongodbatlas_database_user.my_user will be created + resource "mongodbatlas_database_user" "my_user" { + auth_database_name = "admin" + id = (known after apply) + password = (sensitive value) + project_id = (known after apply) + username = "jww" + x509_type = "NONE" + labels { + key = (known after apply) + value = (known after apply) } + roles { + collection_name = (known after apply) + 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) + name = "atlasProjectName" + org_id = "5d3716bfcf09a21576d7983e" } # mongodbatlas_project_ip_whitelist.my_ipaddress will be created + resource "mongodbatlas_project_ip_whitelist" "my_ipaddress" { + aws_security_group = (known after apply) + cidr_block = (known after apply) + comment = "My IP Address" + id = (known after apply) + ip_address = "204.210.139.18" + project_id = (known after apply) } Plan: 4 to add, 0 to change, 0 to destroy. ------------------------------------------------------------------------ Note: You didn't specify an "-out" parameter to save this plan, so Terraform can't guarantee that exactly these actions will be performed if "terraform apply" is subsequently run.

    Proceed to the next step if the information is correct.

    4

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

    terraform apply

    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 MongoDB for VS Code with the displayed connection strings:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    Outputs: connection_strings = [ [ { "aws_private_link" = {} "aws_private_link_srv" = {} "private" = "" "private_srv" = "" "standard" = "mongodb://myCluster-shard-00-00-xxxxx.mongodb.net:27017,myCluster-shard-00-01-xxxxx.mongodb.net:27017,myCluster-shard-00-02-xxxxx.mongodb.net:27017/?ssl=true&authSource=admin&replicaSet=myCluster-shard-0" "standard_srv" = "mongodb+srv://myCluster-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:

    1
    2

    Run the terraform destroy command to install the required providers.

    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.