All Products
Search

This Product

    Alibaba Cloud Service Mesh:Use Terraform to manage ASM instances

    Document Center

    Alibaba Cloud Service Mesh:Use Terraform to manage ASM instances

    Last Updated:Dec 03, 2025

    Terraform is an open source tool provided by HashiCorp for cloud resource orchestration. Terraform lets you securely and efficiently preview, configure, and manage cloud infrastructures and resources. You can use Terraform to automatically create and update resources on the Alibaba Cloud infrastructure. This topic describes how to create and delete a Service Mesh (ASM) instance using Terraform.

    Prerequisites

    • Terraform is installed and configured on your on-premises machine. For more information, see Install and configure Terraform in the local PC.

    • Your Alibaba Cloud account is configured. Environment variables are created to specify your authentication credentials and region information. 

      # Replace YOUR_ACCESS_KEY_ID and YOUR_ACCESS_KEY_SECRET in the following commands with the ID and secret of your Alibaba Cloud account AccessKey.
export ALICLOUD_ACCESS_KEY="YOUR_ACCESS_KEY_ID"
export ALICLOUD_SECRET_KEY="YOUR_ACCESS_KEY_SECRET"
# Replace the value with the region ID of the cluster.
export ALICLOUD_REGION="cn-beijing"
# If the cluster is in a US region, configure the following environment variable to use the US endpoint.
export ALIBABA_CLOUD_ENDPOINT_SERVICEMESH="servicemesh.us-east-1.aliyuncs.com"
      Note

      To improve the flexibility and security of permission management, we recommend that you create a Resource Access Management (RAM) user named Terraform. Then, create an AccessKey pair for the RAM user and grant permissions to the RAM user. For more information, see Create a RAM user and Grant permissions to a RAM user.

    Background information

    For more information about Terraform, visit the official website of Terraform.

    Create an ASM instance

    1. Create a configuration file named main.tf locally.

      • If you do not have a virtual private cloud (VPC) or a vSwitch, create a main.tf file that contains the following content: 

        terraform {
  required_providers {
    alicloud = {
      source = "aliyun/alicloud"
    }
  }
}

variable "k8s_name_prefix" {
  description = "The name prefix used to create Service Mesh (ASM)."
  default     = "tf-asm"
}

resource "random_uuid" "this" {}

# The default resource names and configurations. 
locals {
  # The name of the ASM instance. 
  mesh_name = substr(join("-", [var.k8s_name_prefix, random_uuid.this.result]), 0, 63)
  # The edition of the ASM instance. Valid values: enterprise and ultimate, which indicate Enterprise Edition and Ultimate Edition. 
  mesh_spec = "enterprise"
  # The name of the VPC to be created. 
  new_vpc_name = "vpc-for-${local.mesh_name}"
  # The name of the vSwitch to be created. 
  new_vsw_name = "vsw-for-${local.mesh_name}"
}

# The zone in which you can create a vSwitch. 
data "alicloud_zones" "default" {
  available_resource_creation = "VSwitch"
}
# The VPC. 
resource "alicloud_vpc" "default" {
  vpc_name = local.new_vpc_name
}
# The vSwitch. 
resource "alicloud_vswitch" "default" {
  vpc_id       = alicloud_vpc.default.id
  cidr_block   = cidrsubnet(alicloud_vpc.default.cidr_block, 8, 2)
  zone_id      = data.alicloud_zones.default.zones.0.id
  vswitch_name = local.new_vsw_name
}
# Query the ASM editions available for creating the ASM instance. 
data "alicloud_service_mesh_versions" "default" {
  edition = local.mesh_spec == "standard" ? "Default" : "Pro"
}
# Select the first available edition to create the ASM instance. 
locals {
  mesh_version = split(":", data.alicloud_service_mesh_versions.default.ids[0])[1]
}
# The ASM instance. 
resource "alicloud_service_mesh_service_mesh" "default" {
  # The name of the ASM instance. 
  service_mesh_name = local.mesh_name
  # The network configurations of the ASM instance. 
  network {
    # The ID of the VPC. 
    vpc_id        = alicloud_vpc.default.id
    # The ID of the vSwitch. 
    vswitche_list = [alicloud_vswitch.default.id]
  }
  # The edition of the ASM instance. 
  version = local.mesh_version
  # The load balancer for exposing the API servers and Istio Pilot of the ASM instance. 
  load_balancer {
    # Specify whether to expose the load balancer for the API servers of the ASM instance using an elastic IP address (EIP). 
    api_server_public_eip = true
  }

  # Configure the ASM instance by defining Mesh Config options. 
  mesh_config {
    # Collect access logs to Alibaba Cloud Simple Log Service. 
    access_log {
      enabled = true
    }

    # Enable the collection of control plane logs. To enable this feature, make sure that you have enabled Simple Log Service. 
    control_plane_log {
      enabled = true
    }

    # Enable Tracing Analysis in Application Real-Time Monitoring Service (ARMS). 
    tracing = true

    # If Tracing Analysis is enabled, set the sampling percentage. 
    pilot {
      trace_sampling = 100
    }

    # Enable Prometheus monitoring. 
    telemetry = true

    # Enable Mesh Topology. To enable Mesh Topology, make sure that you have enabled Prometheus monitoring. 
    kiali {
      enabled = true
    }

    # Enable the mesh audit feature. To enable this feature, make sure that you have enabled Simple Log Service. 
    audit {
      enabled = true
    }
  }
  # The edition of the ASM instance. Valid values: enterprise and ultimate, which indicate Enterprise Edition and Ultimate Edition. 
  cluster_spec = local.mesh_spec
}

        Set the parameters described in the following table in the main.tf file as needed. Terraform automatically calls relevant API operations to obtain the values of the other parameters.

        Parameter

        Description

        mesh_name

        The custom name of the Service Mesh instance.

        mesh_spec

        The edition of the Service Mesh instance. Valid values:

        • Standard: Standard Edition (Free).

        • enterprise: Enterprise Edition

        • ultimate: Ultimate Edition

        new_vpc_name

        The custom name of the VPC.

        new_vsw_name

        The custom name of the vSwitch.

        api_server_public_eip

        Specifies whether to expose the load balancer for the API servers of the Service Mesh instance using an EIP. Valid values:

        • true: exposes the load balancer for the API servers of the Service Mesh instance using an EIP.

        • false: does not expose the load balancer for the API servers of the Service Mesh instance using an EIP.

      • If you have created a VPC and a vSwitch, create a main.tf file that contains the following content:

        Important

        The VPC and vSwitch must belong to the region that you specified in the ALICLOUD_REGION environment variable when you configured Terraform. Otherwise, Terraform cannot recognize the VPC or vSwitch. 

        terraform {
  required_providers {
    alicloud = {
      source = "aliyun/alicloud"
    }
  }
}

variable "asm_name_prefix" {
  description = "The name prefix used to create Service Mesh (ASM)."
  default     = "tf-asm"
}

resource "random_uuid" "this" {}

# The default resource names and configurations. 
locals {
  # The name of the ASM instance. 
  mesh_name = substr(join("-", [var.asm_name_prefix, random_uuid.this.result]), 0, 63)
  # The edition of the ASM instance. Valid values: enterprise and ultimate, which indicate Enterprise Edition and Ultimate Edition. 
  mesh_spec = "enterprise"
  # The name of the created VPC. 
  vpc_name = "vpc-luying-hangzhou1"
  # The name of the created vSwitch. 
  vsw_name = "vsw-luying-hangzhou1"
}

# The VPC. 
data "alicloud_vpcs" "default" {
  name_regex = local.vpc_name # The name of the created VPC. 
}
# The vSwitch. 
data "alicloud_vswitches" "default" {
  vpc_id = data.alicloud_vpcs.default.ids[0]
}
locals {
  exist_vswitch_ids = [for vsw in data.alicloud_vswitches.default.vswitches : vsw.id if vsw.name == local.vsw_name]
}
# Query the ASM editions available for creating the ASM instance. 
data "alicloud_service_mesh_versions" "default" {
  edition = local.mesh_spec == "standard" ? "Default" : "Pro"
}
# Select the first available edition to create the ASM instance. 
locals {
  mesh_version = split(":", data.alicloud_service_mesh_versions.default.ids[0])[1]
}
# The ASM instance. 
resource "alicloud_service_mesh_service_mesh" "default" {
  # The name of the ASM instance. 
  service_mesh_name = local.mesh_name
  # The network configurations of the ASM instance. 
  network {
    # The ID of the VPC. 
    vpc_id        =  data.alicloud_vpcs.default.ids[0]
    # The ID of the vSwitch. 
    vswitche_list = [local.exist_vswitch_ids[0]]
  }
  # The edition of the ASM instance. 
  version = local.mesh_version
  # The load balancer for exposing the load balancer for the API servers and Istio Pilot of the ASM instance. 
  load_balancer {
    # Specify whether to expose the load balancer for the API servers of the ASM instance using an EIP. 
    api_server_public_eip = true
  }

  # Configure the ASM instance by defining Mesh Config options. 
  mesh_config {
    # Collect access logs to Alibaba Cloud Simple Log Service. 
    access_log {
      enabled = true
    }

    # Enable the collection of control plane logs. To enable this feature, make sure that you have enabled Simple Log Service. 
    control_plane_log {
      enabled = true
    }

    # Enable Tracing Analysis in ARMS. 
    tracing = true

    # If Tracing Analysis is enabled, set the sampling percentage. 
    pilot {
      trace_sampling = 100
    }

    # Enable Prometheus monitoring. 
    telemetry = true

    # Enable Mesh Topology. To enable Mesh Topology, make sure that you have enabled Prometheus monitoring. 
    kiali {
      enabled = true
    }

    # Enable the mesh audit feature. To enable this feature, make sure that you have enabled Simple Log Service. 
    audit {
      enabled = true
    }
  }
  # The edition of the ASM instance. Valid values: enterprise and ultimate, which indicate Enterprise Edition and Ultimate Edition. 
  cluster_spec = local.mesh_spec
}

        Set the parameters described in the following table in the main.tf file as needed. Terraform automatically calls relevant API operations to obtain the values of the other parameters.

        Parameter

        Description

        mesh_name

        The custom name of the Service Mesh instance.

        mesh_spec

        The edition of the Service Mesh instance. Valid values:

        • Standard: Standard Edition (Free)

        • enterprise: Enterprise Edition

        • ultimate: Ultimate Edition

        vpc_name

        The name of the created VPC.

        vsw_name

        The name of the created vSwitch.

        api_server_public_eip

        Specifies whether to expose the load balancer for the API servers of the Service Mesh instance using an EIP.

        • true: exposes the load balancer for the API servers of the Service Mesh instance using an EIP.

        • false: does not expose the load balancer for the API servers of the Service Mesh instance using an EIP.

    2. Run the following command to initialize the runtime environment for Terraform: 

      terraform init

      Expected output:

      Initializing the backend...

Initializing provider plugins...
- Finding aliyun/alicloud versions matching "1.166.0"...
- Finding latest version of hashicorp/random...
...

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. Run the following command to create an execution plan for Terraform: 

      terraform plan

      Expected output:

      Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols:
  + create

Terraform will perform the following actions:
...
Plan: 2 to add, 0 to change, 0 to destroy.

    4. Run the following command to create an ASM instance using the main.tf file: 

      terraform apply

      Expected output:

      alicloud_service_mesh_service_mesh.example: Refreshing state...
...
Do you want to perform these actions?
  Terraform will perform the actions described above.
  Only 'yes' will be accepted to approve.

  Enter a value:

      Enter yes on the right side of Enter a value. Expected output:

      ...
alicloud_service_mesh_service_mesh.default: Creating...
alicloud_service_mesh_service_mesh.default: Still creating... [10s elapsed]
...
alicloud_service_mesh_service_mesh.example: Creation complete after 2m42s [id=**********]

Apply complete! Resources: 2 added, 0 changed, 0 destroyed.

    Delete an ASM instance

    To run the destroy command in Terraform to delete an ASM instance, you must go to the directory in which the main.tf file resides.

    Go to the directory in which the main.tf file resides and run the following command to delete an ASM instance: 

    terraform destroy

    Expected output:

    ...
Do you really want to destroy all resources?
  Terraform will destroy all your managed infrastructure, as shown above.
  There is no undo. Only 'yes' will be accepted to confirm.

  Enter a value:

    Enter yes on the right side of Enter a value. Expected output:

    ...
Destroy complete! Resources: 2 destroyed.

    Change the attributes of an ASM instance

    You can change the attribute definitions in the .tf file and run the terraform apply command to apply the changes to the ASM instance. The following example changes the http10_enabled attribute. You can refer to this example to change the attributes of an ASM instance using Terraform.

    1. This example uses the .tf file for a scenario in which a VPC and a virtual switch already exist. Change the value of the mesh_config.pilot.http10_enabled property for the service mesh resource to true.

      terraform {
  required_providers {
    alicloud = {
      source = "aliyun/alicloud"
    }
  }
}

variable "asm_name_prefix" {
  description = "The name prefix used to create Service Mesh (ASM)."
  default     = "tf-asm"
}

resource "random_uuid" "this" {}

# The default resource names and configurations. 
locals {
  # The name of the ASM instance. 
  mesh_name = substr(join("-", [var.asm_name_prefix, random_uuid.this.result]), 0, 63)
  # The edition of the ASM instance. Valid values: enterprise and ultimate, which indicate Enterprise Edition and Ultimate Edition. 
  mesh_spec = "enterprise"
  # The name of the created VPC. 
  vpc_name = "prod-hz-vpc"
  # The name of the created vSwitch. 
  vsw_name = "prod-hz-vpc-default"
}

# The VPC. 
data "alicloud_vpcs" "default" {
  name_regex = local.vpc_name # The name of the created VPC. 
}
# The vSwitch. 
data "alicloud_vswitches" "default" {
  vpc_id = data.alicloud_vpcs.default.ids[0]
}
locals {
  exist_vswitch_ids = [for vsw in data.alicloud_vswitches.default.vswitches : vsw.id if vsw.name == local.vsw_name]
}
# Query the ASM editions available for creating the ASM instance. 
data "alicloud_service_mesh_versions" "default" {
  edition = local.mesh_spec == "standard" ? "Default" : "Pro"
}
# Select the first available edition to create the ASM instance. 
locals {
  mesh_version = split(":", data.alicloud_service_mesh_versions.default.ids[0])[1]
}
# The ASM instance. 
resource "alicloud_service_mesh_service_mesh" "default" {
  # The name of the ASM instance. 
  service_mesh_name = local.mesh_name
  # The network configurations of the ASM instance. 
  network {
    # The ID of the VPC. 
    vpc_id        =  data.alicloud_vpcs.default.ids[0]
    # The ID of the vSwitch. 
    vswitche_list = [local.exist_vswitch_ids[0]]
  }
  # The edition of the ASM instance. 
  version = local.mesh_version
  # The load balancer for exposing the API servers and Istio Pilot of the ASM instance. 
  load_balancer {
    # Specify whether to expose the load balancer for the API servers of the ASM instance using an EIP. 
    api_server_public_eip = true
  }

  # Configure the ASM instance by defining Mesh Config options. 
  mesh_config {
    # Collect access logs to Alibaba Cloud Simple Log Service. 
    access_log {
      enabled = true
    }

    # Enable the collection of control plane logs. To enable this feature, make sure that you have enabled Simple Log Service. 
    control_plane_log {
      enabled = true
      project = "mesh-log-cab09b566d4a64c1fa05271d5365495f1"
    }

    # Enable Tracing Analysis in ARMS. 
    tracing = true

    # If Tracing Analysis is enabled, set the sampling percentage. 
    pilot {
      trace_sampling = 100
      http10_enabled = true 
    }

    # Enable Prometheus monitoring. 
    telemetry = true

    # Enable Mesh Topology. To enable Mesh Topology, make sure that you have enabled Prometheus monitoring. 
    kiali {
      enabled = true
    }

    # Enable the mesh audit feature. To enable this feature, make sure that you have enabled Simple Log Service. 
    audit {
      enabled = true
    }
  }
  # The edition of the ASM instance. Valid values: enterprise and ultimate, which indicate Enterprise Edition and Ultimate Edition. 
  cluster_spec = local.mesh_spec
}

    2. Run terraform apply. The output shows the planned change for the field.

      terraform apply
random_uuid.this: Refreshing state... [id=6ab24265-2381-dad9-3be5-351329c5665a]
data.alicloud_vpcs.default: Reading...
data.alicloud_service_mesh_versions.default: Reading...
data.alicloud_service_mesh_versions.default: Read complete after 1s [id=605899410]
data.alicloud_vpcs.default: Read complete after 1s [id=2909606812]
data.alicloud_vswitches.default: Reading...
data.alicloud_vswitches.default: Read complete after 0s [id=866499268]
alicloud_service_mesh_service_mesh.default: Refreshing state... [id=cab09b566d4a64c1fa05271d5365495f1]

Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols:
  ~ update in-place

Terraform will perform the following actions:

  # alicloud_service_mesh_service_mesh.default will be updated in-place
  ~ resource "alicloud_service_mesh_service_mesh" "default" {
        id                = "cab09b566d4a64c1fa05271d5365495f1"
        # (6 unchanged attributes hidden)

      ~ mesh_config {
            # (5 unchanged attributes hidden)

          ~ pilot {
              ~ http10_enabled = false -> true
                # (1 unchanged attribute hidden)
            }

            # (7 unchanged blocks hidden)
        }

        # (2 unchanged blocks hidden)
    }

Plan: 0 to add, 1 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:

    3. Enter yes to apply the change.

      ...Omit irrelevant content...
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_service_mesh_service_mesh.default: Modifying... [id=cab09b566d4a64c1fa05271d5365495f1]
alicloud_service_mesh_service_mesh.default: Still modifying... [id=cab09b566d4a64c1fa05271d5365495f1, 10s elapsed]
alicloud_service_mesh_service_mesh.default: Still modifying... [id=cab09b566d4a64c1fa05271d5365495f1, 20s elapsed]
alicloud_service_mesh_service_mesh.default: Still modifying... [id=cab09b566d4a64c1fa05271d5365495f1, 30s elapsed]
alicloud_service_mesh_service_mesh.default: Modifications complete after 37s [id=cab09b566d4a64c1fa05271d5365495f1]

    Add or remove a Kubernetes cluster

    You can modify the `cluster_ids` array in the .tf file. To add a cluster for ASM to manage, append its ID to the array. To remove a cluster from ASM, delete its ID from the array. Then, run `terraform apply` to apply the changes to the ASM instance.

    1. This example shows how to add a cluster to an ASM instance. Modify the cluster_ids of the service mesh resource by appending the cluster ID to the array:

      ......Omit irrelevant content......
# The ASM instance.
resource "alicloud_service_mesh_service_mesh" "default" {
  # The name of the service mesh.
  service_mesh_name = local.mesh_name
  # The network configuration of the service mesh.
  network {
    # The VPC ID.
    vpc_id        =  data.alicloud_vpcs.default.ids[0]
    # The virtual switch ID.
    vswitche_list = [local.exist_vswitch_ids[0]]
  }
  # The version of the service mesh.
  version = local.mesh_version
  # The load balancer configuration for the API Server and Pilot of the service mesh.
  load_balancer {
    # Specifies whether to use an EIP to expose the API Server through a load balancer.
    api_server_public_eip = true
  }
  cluster_ids = [
    "c94a1a1d968e04c55861b8747********" # Add the cluster ID to the array.
  ]
  ......Omit irrelevant content......
}
......Omit irrelevant content......

    2. Run `terraform apply`. The output shows the planned change to the data plane cluster ID array.

      random_uuid.this: Refreshing state... [id=6ab24265-2381-dad9-3be5-351329c5665a]
data.alicloud_service_mesh_versions.default: Reading...
data.alicloud_vpcs.default: Reading...
data.alicloud_vpcs.default: Read complete after 1s [id=2909606812]
data.alicloud_vswitches.default: Reading...
data.alicloud_vswitches.default: Read complete after 0s [id=866499268]
data.alicloud_service_mesh_versions.default: Read complete after 1s [id=3077056360]
alicloud_service_mesh_service_mesh.default: Refreshing state... [id=c71fe2f2301234701b2e4116397426342]

Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols:
  ~ update in-place

Terraform will perform the following actions:

  # alicloud_service_mesh_service_mesh.default will be updated in-place
  ~ resource "alicloud_service_mesh_service_mesh" "default" {
      ~ cluster_ids       = [
          + "c94a1a1d968e04c55861b8747********",
        ]
        id                = "c71fe2f2301234701b2e4116397426342"
        tags              = {}
        # (6 unchanged attributes hidden)
    }

Plan: 0 to add, 1 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:

    3. Enter yes to apply the change.

      ...Omit irrelevant content...
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_service_mesh_service_mesh.default: Modifying... [id=c71fe2f2301234701b2e4116397426342]
alicloud_service_mesh_service_mesh.default: Still modifying... [id=c71fe2f2301234701b2e4116397426342, 10s elapsed]
alicloud_service_mesh_service_mesh.default: Still modifying... [id=c71fe2f2301234701b2e4116397426342, 20s elapsed]
alicloud_service_mesh_service_mesh.default: Still modifying... [id=c71fe2f2301234701b2e4116397426342, 30s elapsed]
alicloud_service_mesh_service_mesh.default: Still modifying... [id=c71fe2f2301234701b2e4116397426342, 40s elapsed]
alicloud_service_mesh_service_mesh.default: Still modifying... [id=c71fe2f2301234701b2e4116397426342, 50s elapsed]
alicloud_service_mesh_service_mesh.default: Still modifying... [id=c71fe2f2301234701b2e4116397426342, 1m0s elapsed]
alicloud_service_mesh_service_mesh.default: Still modifying... [id=c71fe2f2301234701b2e4116397426342, 1m10s elapsed]
alicloud_service_mesh_service_mesh.default: Still modifying... [id=c71fe2f2301234701b2e4116397426342, 1m20s elapsed]
alicloud_service_mesh_service_mesh.default: Still modifying... [id=c71fe2f2301234701b2e4116397426342, 1m30s elapsed]
alicloud_service_mesh_service_mesh.default: Still modifying... [id=c71fe2f2301234701b2e4116397426342, 1m40s elapsed]
alicloud_service_mesh_service_mesh.default: Modifications complete after 1m44s [id=c71fe2f2301234701b2e4116397426342]

Apply complete! Resources: 0 added, 1 changed, 0 destroyed.

    Terraform resources and data sources

    The following table describes the Terraform resources and data sources that can be used to manage ASM resources.

    Type

    Name

    Description

    Resources

    alicloud_service_mesh_service_mesh

    Manages ASM instances.

    alicloud_service_mesh_user_permission

    Configures permissions on ASM instances.

    Data Sources

    alicloud_service_mesh_service_meshes

    Queries all ASM instances.

    alicloud_service_mesh_versions

    Queries all available Service Mesh versions.

    What do I do if a prompt indicates that some fields will be deleted when I run the terraform apply command?

    To simplify operations, the server assigns default values to some ASM properties even if you do not specify them during creation. This is similar to the Computed attribute tag in Terraform. However, if these properties were set as Computed, their values could not be changed to empty values, such as an empty string, the number 0, or a Boolean value of false. To allow these properties to be changed to empty values, the ASM Terraform provider does not set them as Computed. When you run terraform apply, the server returns these properties. If they are not explicitly declared in your .tf file, Terraform assumes you want to delete their values. If you do not want to delete these properties, you must manually add them to your .tf file as prompted and run terraform apply again.