Navigation

Create an Atlas Cluster from a Template using Terraform

On this page

  • Prerequisites
  • Procedures
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:

  • Install MongoDB for VS Code
  • Install Terraform
  • Have an Atlas account.
  • Have an Atlas organization.
  • Have an API key in an organization with the Organization Owner or Organization Project Creator role.

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

1
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
2
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:

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_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

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_api_pub_key
Atlas public API key.
mongodb_atlas_api_pri_key
Atlas private API key.
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_whitelistip
IP address or CIDR block from which your Atlas cluster is accessible.
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.

    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

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

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.

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

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.

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

On this page

  • Prerequisites
  • Procedures