Purchase and enable a software key management instance with Terraform - Key Management Service

This topic describes how to use Terraform to purchase and enable a software key management instance in Key Management Service (KMS).

Overview

When you purchase and enable a software key management instance, you must attach a virtual private cloud (VPC) and a vSwitch to it. You can also associate multiple VPCs with the KMS instance. After the configuration is complete, a CA instance certificate is generated. You must keep this certificate in a secure location and use it to configure applications that need to access the KMS instance.

Preparations

Prepare a RAM user and grant permissions

For security purposes, we recommend that you use a Resource Access Management (RAM) user instead of your Alibaba Cloud account.

Create a RAM user: For more information, see Create a RAM user.
Create an AccessKey: Create and record an AccessKey for the RAM user. For more information, see Create an AccessKey.

Grant permissions to the RAM user: Terraform requires the AliyunKMSFullAccess, AliyunVPCFullAccess, and AliyunBSSFullAccess permissions to create and manage cloud resources. To follow the least privilege principle, use the following custom policy for authorization. For more information, see 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
You can run Terraform in any of the following ways:
Important
Make sure that your Terraform version is v0.12.28 or later. You can run the terraform --version command to check the version.
1. Terraform Explorer: An online runtime environment provided by Alibaba Cloud. You can use it immediately after you log on, with no installation required. This method is suitable for scenarios where you want to try Terraform quickly at no cost.
2. Cloud Shell: Terraform is pre-installed in Cloud Shell, and your identity credentials are automatically configured. This method is suitable for scenarios where you want to run commands quickly and easily in the cloud.
3. Install and configure Terraform locally: This method is suitable for scenarios with poor network connectivity or where a custom development environment is required.
Check the Aliyun/Alicloud Provider version
Some features have specific version requirements for the Aliyun/Alicloud provider:
- Set auto-renewal upon creation: To set auto-renewal when you create a KMS instance, the provider version must be 1.245.0 or later.
- Change to auto-renewal: To change the renewal method of an existing KMS instance from manual renewal to auto-renewal, the provider version must be 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.

Important

Some resources used in this tutorial incur fees. Release them promptly when they are no longer needed.

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"
}

You can run the following command to initialize the Terraform runtime environment.

terraform init

The following output indicates that Terraform is initialized.

...

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

Run the following command to create the KMS instance.

terraform apply

When prompted, enter yes and press the Enter key. The following output indicates 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
You can run the following command to query the details of the resources created by Terraform:
```
terraform show
```
Log on to the Key Management Service console
Log on to the Key Management Service console and view the KMS instance that you created.

Clean up resources

When you no longer need the resources that were created by Terraform, run the following command to release them. For more information about terraform destroy, see Common commands.

terraform destroy

Complete example

Note

You can run the sample code in this topic 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"
}