Navigation

    Create an Atlas Cluster from a Template using Terraform

    Info With Circle IconCreated with Sketch.Note
    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.

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

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

    1
    Operating SystemMethodActions
    AnyVisual Studio Code MenuFile > New File
    MacOSKeyboard ShortcutPress Command + N
    Windows and LinuxKeyboard ShortcutPress Control + N
    2
    Info With Circle IconCreated with Sketch.Note

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

    3

    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

    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:

    Bulb IconTip

    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
    Warning IconCreated with Sketch.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.
    Info With Circle IconCreated with Sketch.Note
    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.

      Beaker IconExample
      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..

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

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

    Info With Circle IconCreated with Sketch.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

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

    1
    2
    terraform init

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

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

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

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

    Proceed to the next step if the information is correct.

    4
    terraform apply

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

    Info With Circle IconCreated with Sketch.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:

    1Apply complete! Resources: 4 added, 0 changed, 0 destroyed.
    2
    3Outputs:
    4
    5connection_strings = [
    6 [
    7 {
    8 "aws_private_link" = {}
    9 "aws_private_link_srv" = {}
    10 "private" = ""
    11 "private_srv" = ""
    12 "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"
    13 "standard_srv" = "mongodb+srv://myCluster-xxxxx.mongodb.net"
    14 },
    15 ],
    16]
    Warning IconCreated with Sketch.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
    terraform destroy

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

    Info With Circle IconCreated with Sketch.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.
    Give Feedback