Create an Atlas Cluster from a Template using Terraform
On this page
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:
Have an Atlas account.
Have an Atlas organization.
Have an API key in an organization with the
Organization Owner
orOrganization 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 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.
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_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:
|
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:
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:
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 details about the disk sizes that each provider supports for each instance size, see the following sections in the Atlas documentation: |
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_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. |
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_api_pub_key" { default = "my-public-key" } variable "mongodb_atlas_api_pri_key" { default = "my-private-key" } 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 withvars.
.provider "mongodbatlas" { public_key = vars.mongodb_atlas_api_pub_key private_key = vars.mongodb_atlas_api_pri_key }
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.
Create the Atlas Cluster using Terraform
After you create a Terraform file using the template, create the Atlas cluster:
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 Initializing the backend... 2 3 Initializing provider plugins... 4 - Checking for available provider plugins... 5 - Downloading plugin for provider "mongodbatlas" (terraform-providers/mongodbatlas) 0.5.1... 6 7 The following providers do not have any version constraints in configuration, 8 so the latest version was installed. 9 10 To prevent automatic upgrades to new major versions that may contain breaking 11 changes, it is recommended to add version = "..." constraints to the 12 corresponding provider blocks in configuration, with the constraint strings 13 suggested below. 14 15 * provider.mongodbatlas: version = "~> 0.5" 16 17 Terraform has been successfully initialized!
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 Refreshing Terraform state in-memory prior to plan... 2 The refreshed state will be used to calculate this plan, but will not be 3 persisted to local or remote state storage. 4 5 6 ------------------------------------------------------------------------ 7 8 An execution plan has been generated and is shown below. 9 Resource actions are indicated with the following symbols: 10 + create 11 12 Terraform 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 110 Plan: 4 to add, 0 to change, 0 to destroy. 111 112 ------------------------------------------------------------------------ 113 114 Note: You didn't specify an "-out" parameter to save this plan, so Terraform 115 can'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.
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 VS Code Extension with the displayed connection strings:
1 Apply complete! Resources: 4 added, 0 changed, 0 destroyed. 2 3 Outputs: 4 5 connection_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 ]
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:
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.