All Products
Search

This Product

    ApsaraDB for MongoDB:Integrate ApsaraDB for MongoDB by using Terraform

    Document Center

    ApsaraDB for MongoDB:Integrate ApsaraDB for MongoDB by using Terraform

    Last Updated:Jun 25, 2026

    This topic describes how to use Terraform to create an ApsaraDB for MongoDB instance.

    Note

    You can run the sample code in this topic with a few clicks.

    For more information about Terraform, see What is Terraform? For more information about the MongoDB resource types supported by Terraform, see Integration overview or Alibaba Cloud Provider.

    Resource architecture

    image.png

    The template creates a VPC and a vSwitch in a specified region, and then creates a MongoDB replica set instance.

    Prerequisites

    • An Alibaba Cloud account has full permissions on all resources that belong to this account. If the credentials of the Alibaba Cloud account are leaked, security risks may arise. We recommend that you use a Resource Access Management (RAM) user and create an AccessKey pair for the RAM user. For more information, see Create a RAM user and Create an AccessKey pair.

    • The AliyunMongoDBFullAccess and AliyunMongoDBFullAccess permissions are granted to the RAM user. The AliyunMongoDBFullAccess permission is used to manage ApsaraDB for MongoDB, and the AliyunMongoDBFullAccess permission is used to manage virtual private clouds (VPCs). The following sample code shows an example on how to grant the two permissions to the RAM user. For more information, see Grant permissions to a RAM user 

      {
    "Version": "1",
    "Statement": [
        {
            "Action": "dds:*",
            "Resource": "*",
            "Effect": "Allow"
        },
        {
            "Action": [
                "vpc:DescribeVpcs",
                "vpc:DescribeVSwitches",
                "vpc:CreateVpc",
                "vpc:DeleteVpc",
                "vpc:ModifyVpcAttribute",
                "vpc:CreateVSwitch",
                "vpc:DeleteVSwitch",
                "vpc:ModifyVSwitchAttribute"
            ],
            "Resource": "*",
            "Effect": "Allow"
        },
        {
            "Action": "hdm:*",
            "Resource": "acs:dds:*:*:*",
            "Effect": "Allow"
        },
        {
            "Action": "dms:LoginDatabase",
            "Resource": "acs:dds:*:*:*",
            "Effect": "Allow"
        },
        {
            "Action": "ram:CreateServiceLinkedRole",
            "Resource": "*",
            "Effect": "Allow",
            "Condition": {
                "StringEquals": {
                    "ram:ServiceName": "mongodb.aliyuncs.com"
                }
            }
        }
    ]
}

    • Prepare the runtime environment for Terraform by using one of the following methods:

      • Use Terraform in Terraform Explorer: Alibaba Cloud provides Terraform Explorer, an online runtime environment for Terraform. You can use Terraform after you log on to Terraform Explorer without the need to install Terraform. This method is suitable for scenarios in which you want to use and debug Terraform in a fast and convenient manner at no additional costs.

      • Use Terraform in Cloud Shell: Terraform is preinstalled in Cloud Shell and identity credentials are configured. You can directly run Terraform commands in Cloud Shell. This method is suitable for scenarios in which you want to use and debug Terraform in a fast and convenient manner at low costs.

      • Install and configure Terraform on your on-premises machine: This method is suitable for scenarios in which network connections are unstable or a custom development environment is required.

    Important

    You must install Terraform 0.12.28 or later. You can run the terraform --version command to query the Terraform version.

    Note

    Fees are generated for specific resources in this example. Unsubscribe from the resources when you no longer need them.

    Required resources

    Use Terraform to create an ApsaraDB for MongoDB instance.

    1. Create a working directory and a configuration file named main.tf in the directory. main.tf is the main file of Terraform and defines the resources that you want to deploy.

      Standalone instance

      variable "region" {
  default = "cn-heyuan"
}
provider "alicloud" {
  region = var.region
}
# Declare the variable 'name'.
variable "name" {
  default = "terraform-example-1125"
}
variable "engine_version" {
  default = "7.0"
}
variable "db_instance_class" {
  default = "mdb.shard.2x.xlarge.d"
}
# Query for available availability zones.
data "alicloud_mongodb_zones" "default" {
}
# Use a local value to get the last available availability zone ID from the data source.
locals {
  index   = length(data.alicloud_mongodb_zones.default.zones) - 1
  zone_id = data.alicloud_mongodb_zones.default.zones[local.index].id
}
# Create a VPC resource.
resource "alicloud_vpc" "vpc1" {
  vpc_name   = var.name
  cidr_block = "172.16.0.0/12"
}
# Create a vSwitch in the specified availability zone within the VPC.
resource "alicloud_vswitch" "default" {
  vswitch_name = var.name
  cidr_block   = "172.16.20.0/24"
  vpc_id       = alicloud_vpc.vpc1.id
  zone_id      = local.zone_id
}
# Create a standalone instance by using the VPC and vSwitch.
resource "alicloud_mongodb_instance" "singleNode" {
  # (Required) The database version.
  engine_version      = var.engine_version
  # (Required) The instance type.
  db_instance_class   = var.db_instance_class
  # (Required) The storage capacity of the instance, in GB.
  db_instance_storage = 20
  # The network type of the instance.
  network_type        = "VPC"
  # (Optional, ForceNew) The ID of the vSwitch to which the instance is connected in the VPC.
  vswitch_id          = alicloud_vswitch.default.id
  # The ID of the VPC.
  vpc_id              = alicloud_vpc.vpc1.id
  # (Optional, ForceNew) The availability zone where the instance resides.
  zone_id             = local.zone_id
  # The name of the instance.  
  name                = var.name
  # (Optional, available from v1.199.0) The storage type of the instance.
  # storage_type        = "cloud_auto"
  # (Optional) A mapping of tags to assign to the resource.
  # tags = {
  #   Created = "TF"
  #   For     = "example"
  #   }
  # (Optional, List) The list of IP addresses that are allowed to access all databases of the instance.
  # security_ip_list    = [
        # "10.168.1.12",
        # "100.69.7.112"
  #   ]
}

      For more information about how to configure the alicloud_mongodb_instance resource type, see alicloud_mongodb_instance.

      Replica set instance

      variable "region" {
  default = "cn-heyuan"
}
provider "alicloud" {
  region = var.region
}
# Declare the variable 'name'.
variable "name" {
  default = "terraform-example-1125"
}
variable "engine_version" {
  default = "7.0"
}
variable "db_instance_class" {
  default = "mdb.shard.2x.xlarge.d"
}
# Query for available availability zones.
data "alicloud_mongodb_zones" "default" {
}
# Use a local value to get the last available availability zone ID from the data source.
locals {
  index   = length(data.alicloud_mongodb_zones.default.zones) - 1
  zone_id = data.alicloud_mongodb_zones.default.zones[local.index].id
}
# Create a VPC resource.
resource "alicloud_vpc" "vpc1" {
  vpc_name   = var.name
  cidr_block = "172.16.0.0/12"
}
# Create a vSwitch in the specified availability zone within the VPC.
resource "alicloud_vswitch" "default" {
  vswitch_name = var.name
  cidr_block   = "172.16.20.0/24"
  vpc_id       = alicloud_vpc.vpc1.id
  zone_id      = local.zone_id
}
# Create a replica set instance by using the VPC and vSwitch.
resource "alicloud_mongodb_instance" "default" {
  engine_version      = var.engine_version
  db_instance_class   = var.db_instance_class
  db_instance_storage = 20
  network_type        = "VPC"
  vswitch_id          = alicloud_vswitch.default.id
  vpc_id              = alicloud_vpc.vpc1.id
  security_ip_list    = ["10.168.1.12", "100.69.7.112"]
  name                = var.name
  tags = {
    Created = "TF"
    For     = "example"
  }
}

      For more information about how to configure the alicloud_mongodb_instance resource type, see alicloud_mongodb_instance.

      Sharded cluster instance

      variable "region" {
  default = "cn-heyuan"
}
provider "alicloud" {
  region = var.region
}
# Declare the variable 'name'.
variable "name" {
  default = "terraform-example-1125"
}
# Query for available availability zones.
data "alicloud_mongodb_zones" "default" {
}
# Use a local value to get the last available availability zone ID from the data source.
locals {
  index   = length(data.alicloud_mongodb_zones.default.zones) - 1
  zone_id = data.alicloud_mongodb_zones.default.zones[local.index].id
}
# Create a VPC resource.
resource "alicloud_vpc" "vpc1" {
  vpc_name   = var.name
  cidr_block = "172.16.0.0/12"
}
# Create a vSwitch in the specified availability zone within the VPC.
resource "alicloud_vswitch" "default" {
  vswitch_name = var.name
  cidr_block   = "172.16.20.0/24"
  vpc_id       = alicloud_vpc.vpc1.id
  zone_id      = local.zone_id
}
# Create a sharded cluster instance by using the VPC and vSwitch.
resource "alicloud_mongodb_sharding_instance" "default" {
  # (Required) The database version.
  engine_version      = "7.0"
  # (Optional, ForceNew) The vSwitch ID of the instance.
  vswitch_id          = alicloud_vswitch.default.id
  # The network type of the instance.
  network_type        = "VPC"
  # The VPC ID of the instance.
  vpc_id              = alicloud_vpc.vpc1.id
  # The name of the instance.
  name                = var.name
  # The availability zone.
  zone_id = local.zone_id
  # The mongos nodes of the instance. The number of nodes must be between 2 and 32. See mongo_list below.
  mongo_list {
    # (Required) The instance type of the mongos node.
    node_class = "mdb.shard.2x.xlarge.d"
  }
  mongo_list {
    node_class = "mdb.shard.2x.xlarge.d"
  }
  # (Required, Set) The shard nodes of the instance. You can purchase 2 to 32 shard nodes. See shard_list below.
  shard_list {
    # (Required) The instance type of the shard node.
    node_class   = "mdb.shard.2x.xlarge.d"
    #  (Required, Int) The storage space of the shard node.
    node_storage = 20
  }
  shard_list {
    node_class        = "mdb.shard.2x.xlarge.d"
    node_storage      = 20
    # The number of read-only nodes in the shard node. Default value: 0. Valid values: 0 to 5.
    readonly_replicas = 1
  }
  config_server_list {
    # The instance type of the ConfigServer node. Valid values: mdb.shard.2x.xlarge.d and dds.cs.mid.
    node_class ="mdb.shard.2x.xlarge.d"
    # The storage space of the ConfigServer node.
    node_storage = "20"
  }
  # A mapping of tags to assign to the resource.
  tags = {
    Created = "TF"
    For     = "Example"
  }
}

      For more information about how to configure the alicloud_mongodb_sharding_instance resource type, see alicloud_mongodb_sharding_instance.

    2. Run the following command to initialize Terraform: 

      terraform init

      If the following information is returned, Terraform is successfully initialized. 

      Initializing the backend...
Initializing provider plugins...
- Finding latest version of hashicorp/alicloud...
- Installing hashicorp/alicloud v1.234.0...
- Installed hashicorp/alicloud v1.234.0 (signed by HashiCorp)
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 that 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 for Terraform,
rerun this command to reinitialize your working directory. If you forget, other
commands will detect it and remind you to do so if necessary.

    3. Create an execution plan and preview the changes. 

      terraform plan

    4. Run the following command to create an ApsaraDB for MongoDB instance. 

      terraform apply

      When prompted, enter yes and press Enter. The following output indicates that the ApsaraDB for MongoDB instance was created successfully.

      Plan: 3 to add, 0 to change, 0 to destroy.
Do you want to perform these actions?
  Terraform will perform the actions described above.
  Only 'yes' will be accepted to approve.
  Enter a value: yes
alicloud_vpc.vpc1: Creating...
alicloud_vpc.vpc1: Creation complete after 6s [id=vpc-f8zov2h1snsl2bm9qz***]
alicloud_vswitch.default: Creating...
alicloud_vswitch.default: Creation complete after 3s [id=vsw-f8zswqowidqw16ypc2***]
alicloud_mongodb_instance.singleNode: Creating...
alicloud_mongodb_instance.singleNode: Still creating... [10s elapsed]
alicloud_mongodb_instance.singleNode: Still creating... [20s elapsed]
alicloud_mongodb_instance.singleNode: Still creating... [30s elapsed]
alicloud_mongodb_instance.singleNode: Still creating... [40s elapsed]
alicloud_mongodb_instance.singleNode: Still creating... [50s elapsed]
alicloud_mongodb_instance.singleNode: Still creating... [1m0s elapsed]
alicloud_mongodb_instance.singleNode: Still creating... [1m10s elapsed]
...
alicloud_mongodb_instance.singleNode: Still creating... [14m11s elapsed]
alicloud_mongodb_instance.singleNode: Still creating... [14m21s elapsed]
alicloud_mongodb_instance.singleNode: Creation complete after 14m29s [id=dds-f8z3a787aea1c***]
Apply complete! Resources: 3 added, 0 changed, 0 destroyed.

    5. Verify the result.

      Run the terraform show command

      Run the following command to query the resources that are created by Terraform:

      terraform show
      shell@Alicloud:~/ens/mongodb$ terraform show
# alicloud_mongodb_instance.singleNode:
resource "alicloud_mongodb_instance" "singleNode" {
    backup_interval                          = "-1"
    backup_period                            = [
        "Friday",
        "Monday",
        "Saturday",
        "Sunday",
        "Thursday",
        "Tuesday",
        "Wednesday",
    ]
    backup_retention_period                  = 30
    backup_retention_policy_on_cluster_deletion = 0
    backup_time                              = "07:00Z-08:00Z"
    db_instance_class                        = "mdb.shard.2x.xlarge.d"
    db_instance_storage                      = 20
    enable_backup_log                        = 1
    encrypted                                = false
    engine_version                           = "7.0"
    id                                       = "dds xxx"
    instance_charge_type                     = "PostPaid"
    log_backup_retention_period              = 30
    ...
}
    maintain_end_time                        = "22:00Z"
    maintain_start_time                      = "18:00Z"
    name                                     = "terraform-example-1125"
    network_type                             = "VPC"
    provisioned_iops                         = 0
    readonly_replicas                        = 0
    replica_set_name                         = "mgset-84451431"
    replica_sets                             = [
        {
            connection_domain    = "xxx"
            connection_port      = "3717"
            network_type         = "VPC"
            replica_set_role     = "Primary"
            vpc_cloud_instance_id = "xxx"
            vpc_id               = "vpc-xxx"
            vswitch_id           = "vsw-xxx"
        },
    ]
    replication_factor                       = 3
    resource_group_id                        = "xxx"
    retention_period                         = 30
}

      Log on to the ApsaraDB for MongoDB console

      After the instance is created, you can use OpenAPI, SDKs, or log on to the ApsaraDB for MongoDB console to verify that the operation is successful. Log on to the ApsaraDB for MongoDB console and go to the Replica Set Instances page. Verify that the instance created by Terraform is in the Running state and its configuration matches your settings: the instance is in an availability zone in China (Heyuan), the instance class is mdb.shard.2x.xlarge.d, the storage is 20 GB, the version is 7.0, the network type is VPC, the billing method is pay-as-you-go, and the architecture is three-node.

    Release resources

    If you no longer require the preceding resources that are created or managed by Terraform, run the following command to release the resources. For more information about the terraform destroy command, see Common commands. 

    terraform destroy

    Sample code

    Note

    You can run the sample code in this topic with a few clicks.

    Sample code

    variable "region" {
  default = "cn-heyuan"
}
provider "alicloud" {
  region = var.region
}
# Declare the variable 'name'.
variable "name" {
  default = "terraform-example-1125"
}
variable "engine_version" {
  default = "7.0"
}
variable "db_instance_class" {
  default = "mdb.shard.2x.xlarge.d"
}
# Query for available availability zones.
data "alicloud_mongodb_zones" "default" {
}
# Use a local value to get the last available availability zone ID from the data source.
locals {
  index   = length(data.alicloud_mongodb_zones.default.zones) - 1
  zone_id = data.alicloud_mongodb_zones.default.zones[local.index].id
}
# Create a VPC resource.
resource "alicloud_vpc" "vpc1" {
  vpc_name   = var.name
  cidr_block = "172.16.0.0/12"
}
# Create a vSwitch in the specified availability zone within the VPC.
resource "alicloud_vswitch" "default" {
  vswitch_name = var.name
  cidr_block   = "172.16.20.0/24"
  vpc_id       = alicloud_vpc.vpc1.id
  zone_id      = local.zone_id
}
# Create a standalone instance by using the VPC and vSwitch.
resource "alicloud_mongodb_instance" "singleNode" {
  # (Required) The database version.
  engine_version      = var.engine_version
  # (Required) The instance type.
  db_instance_class   = var.db_instance_class
  # (Required) The storage capacity of the instance, in GB.
  db_instance_storage = 20
  # The network type of the instance.
  network_type        = "VPC"
  # (Optional, ForceNew) The ID of the vSwitch to which the instance is connected in the VPC.
  vswitch_id          = alicloud_vswitch.default.id
  # The ID of the VPC.
  vpc_id              = alicloud_vpc.vpc1.id
  # (Optional, ForceNew) The availability zone where the instance resides.
  zone_id             = local.zone_id
  # The name of the instance.  
  name                = var.name
  # (Optional) A mapping of tags to assign to the resource.
  tags = {
    Created = "TF"
    For     = "example"
    }
  # (Optional, List) The list of IP addresses that are allowed to access all databases of the instance.
  security_ip_list    = [
         "10.168.1.12",
         "100.69.7.112"
     ]
  # (Optional, available from v1.199.0) The storage type of the instance.
  # storage_type        = "cloud_auto"   
}
# Create a sharded cluster instance by using the VPC and vSwitch.
resource "alicloud_mongodb_sharding_instance" "default" {
  # (Required) The database version.
  engine_version      = "7.0"
  # (Optional, ForceNew) The vSwitch ID of the instance.
  vswitch_id          = alicloud_vswitch.default.id
  # The network type of the instance.
  network_type        = "VPC"
  # The VPC ID of the instance.
  vpc_id              = alicloud_vpc.vpc1.id
  # The name of the instance.
  name                = var.name
  # The availability zone.
  zone_id = local.zone_id
  # The mongos nodes of the instance. The number of nodes must be between 2 and 32. See mongo_list below.
  mongo_list {
    # (Required) The instance type of the mongos node.
    node_class = "mdb.shard.2x.xlarge.d"
  }
  mongo_list {
    node_class = "mdb.shard.2x.xlarge.d"
  }
  # (Required, Set) The shard nodes of the instance. You can purchase 2 to 32 shard nodes. See shard_list below.
  shard_list {
    # (Required) The instance type of the shard node.
    node_class   = "mdb.shard.2x.xlarge.d"
    #  (Required, Int) The storage space of the shard node.
    node_storage = 20
  }
  shard_list {
    node_class        = "mdb.shard.2x.xlarge.d"
    node_storage      = 20
    # The number of read-only nodes in the shard node. Default value: 0. Valid values: 0 to 5.
    readonly_replicas = 1
  }
  config_server_list {
    # The instance type of the ConfigServer node. Valid values: mdb.shard.2x.xlarge.d and dds.cs.mid.
    node_class ="mdb.shard.2x.xlarge.d"
    # The storage space of the ConfigServer node.
    node_storage = "20"
  }
  # A mapping of tags to assign to the resource.
  tags = {
    Created = "TF"
    For     = "Example"
  }
}

    To view other sample code, visit GitHub.