Use Terraform to purchase and enable a software key management instance - Key Management Service

Overview

A software key management instance requires a VPC and a vSwitch. You can also associate multiple VPCs with the instance. After the configuration is complete, a CA instance certificate is generated. Store this certificate securely — applications that access the KMS instance need it.

Preparations

Prepare a RAM user and grant permissions

For security, use a RAM user instead of your Alibaba Cloud account.

Create a RAM user: Create a RAM user.
Create an AccessKey: Create and record an AccessKey for the RAM user. Create an AccessKey.

Grant permissions to the RAM user: Terraform needs AliyunKMSFullAccess, AliyunVPCFullAccess, and AliyunBSSFullAccess. For least privilege, apply the following custom policy. Grant permissions to a RAM user.

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "kms:*"
      ],
      "Resource": [
        "*"
      ]
    },
    {
      "Effect": "Allow",
      "Action": [
        "vpc:CreateVpc",
        "vpc:CreateVSwitch",
        "vpc:DescribeNatGateways",
        "vpc:DeleteVpc",
        "vpc:DeleteVSwitch"
      ],
      "Resource": [
        "*"
      ]
    },
    {
      "Effect": "Allow",
      "Action": [
        "vpc:DescribeVpcAttribute",
        "vpc:DescribeVSwitchAttributes",
        "vpc:DescribeRouteTableList"
      ],
      "Resource": [
        "*"
      ]
    },
    {
      "Effect": "Allow",
      "Action": [
        "bss:*",
        "bssapi:*"
      ],
      "Resource": [
        "*"
      ]
    }
  ]
}

Prepare the Terraform runtime environment

Run Terraform in any of the following ways:

Important
Terraform v0.12.28 or later is required. Run terraform --version to verify.
1. Terraform Explorer: An online environment from Alibaba Cloud. Log on to use it immediately — no installation required. Best for quick, cost-free trials.
2. Cloud Shell: Terraform is pre-installed and credentials are auto-configured. Best for quick cloud-based execution.
3. Install and configure Terraform locally: Best for environments with limited connectivity or custom setup requirements.
Check the Aliyun/Alicloud Provider version

Some features require a minimum Aliyun/Alicloud provider version:
- Set auto-renewal upon creation: Requires provider 1.245.0 or later.
- Change to auto-renewal: Requires provider 1.257.0 or later.

Resources used

alicloud_vpc: Creates a virtual private cloud (VPC).
alicloud_vswitch: Creates a virtual switch (vSwitch) to divide a VPC into one or more subnets.
alicloud_zones: Queries available zones.
alicloud_kms_instance: Purchases and enables a software key management instance.

Purchase and enable a software key management instance using Terraform

This example creates and enables a KMS instance.

Note

When you enable a software key management instance using Terraform, you can configure only one vSwitch.

Create a working directory and create a configuration file named main.tf in the directory. main.tf is the main Terraform file that defines the resources to be deployed.

variable "region" {
  default = "ap-southeast-1"
}

provider "alicloud" {
  region = var.region
}
variable "instance_name" {
  default = "tf-kms-vpc-172-16"
}

variable "instance_type" {
  default = "ecs.e-c1m2.large"
}
# Use a data source to obtain information about available zones. Resources can be created only in the specified zones.
data "alicloud_zones" "default" {
  available_disk_category     = "cloud_efficiency"
  available_resource_creation = "VSwitch"
  available_instance_type     = var.instance_type
}
# Create a VPC.
resource "alicloud_vpc" "vpc" {
  vpc_name   = var.instance_name
  cidr_block = "172.16.0.0/12"
}
# Create a vSwitch with a CIDR block of 172.16.0.0/21.
resource "alicloud_vswitch" "vsw" {
  vpc_id     = alicloud_vpc.vpc.id
  cidr_block = "172.16.0.0/21"
  zone_id    = data.alicloud_zones.default.zones.0.id
  vswitch_name = "terraform-example-1"
}
# Create a KMS software key management instance and start it using network parameters.
resource "alicloud_kms_instance" "default" {
  # Software key management instance.
  product_version = "3"
  vpc_id          = alicloud_vpc.vpc.id
  # Specify the zones where the KMS instance resides. Use the zone IDs that are obtained.
  zone_ids = [
    data.alicloud_zones.default.zones.0.id,
    data.alicloud_zones.default.zones.1.id
  ]
  # The vSwitch ID.
  vswitch_ids = [
    alicloud_vswitch.vsw.id
  ]
  # The computing performance, number of keys, number of secrets, and number of managed access requests.
  vpc_num    = "1"
  key_num    = "1000"
  secret_num = "100"
  spec       = "1000"
  # Optional. Associate other VPCs with the KMS instance.
  # If a VPC and the VPC of the KMS instance belong to different Alibaba Cloud accounts, you must first share the vSwitch.
  #bind_vpcs {
  #vpc_id = "vpc-j6cy0l32yz9ttxfy6****"
  #vswitch_id = "vsw-j6cv7rd1nz8x13ram****"
  #region_id = "ap-southeast-1"
  #vpc_owner_id = "119285303511****"
  #}
  #bind_vpcs {
  #vpc_id = "vpc-j6cy0l32yz9ttd7g3****"
  #vswitch_id = "vsw-3h4yrd1nz8x13ram****"
  #region_id = "ap-southeast-1"
  #vpc_owner_id = "119285303511****"
  #}
}

# Save the CA certificate of the KMS instance to a local file.
resource "local_file" "ca_certificate_chain_pem" {
  content  = alicloud_kms_instance.default.ca_certificate_chain_pem
  filename = "ca.pem"
}

Initialize the Terraform runtime environment.

terraform init

Successful initialization produces the following output.

...
Terraform has been successfully initialized!
You may now begin working with Terraform. Try running "terraform plan" to see any changes...

Create an execution plan and preview the changes.
```
terraform plan
```

Create the KMS instance.

terraform apply

Enter yes when prompted and press Enter. The following output confirms that the KMS instance is created.

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
...
Apply complete! Resources: 4 added, 0 changed, 0 destroyed.

Verify the result.
Run the terraform show command

Query the details of resources created by Terraform:
```
terraform show
```
Log on to the Key Management Service console

Log on to the Key Management Service console. On the Instance Management page, follow the Application Integration Guide: Authorize Application Access, Obtain Instance CA Certificate, and Complete Application Adaptation. Focus on the last two steps. The Software Key Management tab lists your KMS instances with key capacity, secret capacity, creation time, billing method, and expiration status. You can view Details, manage Resource Sharing, or initiate a Renewal.

Clean up resources

To release Terraform-created resources you no longer need, run the following command. terraform destroy usage is covered in Common commands.

terraform destroy

Complete example

Note

Run the sample code directly with a single click. Run with one click

Sample code

variable "region" {
  default = "ap-southeast-1"
}

provider "alicloud" {
  region = var.region
}
variable "instance_name" {
  default = "tff-kms-vpc-172-16"
}

variable "instance_type" {
  default = "ecs.e-c1m2.large"
}
# Use a data source to obtain information about available zones. Resources can be created only in the specified zones.
data "alicloud_zones" "default" {
  available_disk_category     = "cloud_efficiency"
  available_resource_creation = "VSwitch"
  available_instance_type     = var.instance_type
}
# Create a VPC.
resource "alicloud_vpc" "vpc" {
  vpc_name   = var.instance_name
  cidr_block = "172.16.0.0/12"
}
# Create a vSwitch with a CIDR block of 172.16.0.0/21.
resource "alicloud_vswitch" "vsw" {
  vpc_id     = alicloud_vpc.vpc.id
  cidr_block = "172.16.0.0/21"
  zone_id    = data.alicloud_zones.default.zones.0.id
  vswitch_name = "terraform-example-1"
}
# Create a KMS software key management instance and start it using network parameters.
resource "alicloud_kms_instance" "default" {
  # Software key management instance.
  product_version = "3"
  vpc_id          = alicloud_vpc.vpc.id
  # Specify the zones where the KMS instance resides. Use the zone IDs that are obtained.
  zone_ids = [
    data.alicloud_zones.default.zones.0.id,
    data.alicloud_zones.default.zones.1.id
  ]
  # The vSwitch ID.
  vswitch_ids = [
    alicloud_vswitch.vsw.id
  ]
  # The computing performance, number of keys, number of secrets, and number of managed access requests.
  vpc_num    = "1"
  key_num    = "1000"
  secret_num = "100"
  spec       = "1000"
  # Associate other VPCs with the KMS instance.
  # If a VPC and the VPC of the KMS instance belong to different Alibaba Cloud accounts, you must first share the vSwitch.
  #bind_vpcs {
  #vpc_id = "vpc-j6cy0l32yz9ttxfy6****"
  #vswitch_id = "vsw-j6cv7rd1nz8x13ram****"
  #region_id = "ap-southeast-1"
  #vpc_owner_id = "119285303511****"
  #}
  #bind_vpcs {
  #vpc_id = "vpc-j6cy0l32yz9ttd7g3****"
  #vswitch_id = "vsw-3h4yrd1nz8x13ram****"
  #region_id = "ap-southeast-1"
  #vpc_owner_id = "119285303511****"
  #}
}
# Save the CA certificate of the KMS instance to a local file.
resource "local_file" "ca_certificate_chain_pem" {
  content  = alicloud_kms_instance.default.ca_certificate_chain_pem
  filename = "ca.pem"
}