Create a key by using Terraform - Key Management Service

You can use Terraform to create and manage keys. This topic describes how to create a key.

Overview

Key Management Service (KMS) lets you create a default master key without purchasing a KMS instance. You can also create keys in a KMS instance. For more information about keys, see Key service overview.

Prerequisites

Using an Alibaba Cloud account with full permissions for all its resources poses a high security threat if the credentials are leaked. We recommend that you use a Resource Access Management (RAM) user and create an AccessKey for that user. For more information, see Create a RAM user and Create an AccessKey.
To grant permissions to the RAM user, attach the AliyunKMSFullAccess policy. This policy grants permissions to manage Key Management Service (KMS). For more information, see Manage RAM user permissions.
```
{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "kms:*"
      ],
      "Resource": [
        "*"
      ],
      "Condition": {}
    }
  ]
}
```
Prepare a Terraform environment. You can choose one of the following methods to use Terraform.
Use Terraform in Explorer: Alibaba Cloud provides an online environment for Terraform. You do not need to install Terraform. You can log on to use and test Terraform online. This method is suitable for scenarios where you want to quickly and conveniently test and debug Terraform at no cost.
Cloud Shell: Terraform components are pre-installed in Alibaba Cloud Cloud Shell, and your identity credentials are automatically configured. You can run Terraform commands directly in Cloud Shell. This method is suitable for scenarios where you want to quickly and conveniently access and use Terraform at a low cost.
Install and configure Terraform locally: This method is suitable for scenarios with poor network connectivity or when a custom development environment is required.

Important

Make sure that your Terraform version is 0.12.28 or later. To check your current version, you can run the terraform --version command.

Resources used

alicloud_kms_key: Creates and manages keys.
alicloud_kms_alias: Creates and manages aliases.

Procedure

This example shows how to create a key in a KMS instance.

Create a working directory. In the working directory, create a configuration file named main.tf. main.tf is the main Terraform file that defines the resources to deploy. Before you start, make sure that you have created a KMS instance.

variable "region" {
  default = "cn-shanghai"
}

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

variable "instance_type" {
  default = "ecs.n1.tiny"
}
# 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 the CIDR block 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 another vSwitch with the CIDR block 172.16.128.0/17.
resource "alicloud_vswitch" "vsw1" {
  vpc_id     = alicloud_vpc.vpc.id
  cidr_block = "172.16.128.0/17"
  zone_id    = data.alicloud_zones.default.zones.1.id
  vswitch_name = "terraform-example-2"
}
# Create a software key management instance and start it with network parameters.
resource "alicloud_kms_instance" "default" {
  timeouts {
    delete = "20m" # Set a timeout period for deletion.
  }
  # A software key management instance.
  product_version = "3"
  vpc_id          = alicloud_vpc.vpc.id
  # Specify the zones for the KMS instance using the obtained zone IDs.
  zone_ids = [
    data.alicloud_zones.default.zones.0.id,
    data.alicloud_zones.default.zones.1.id
  ]
  # The vSwitch IDs.
  vswitch_ids = [
    alicloud_vswitch.vsw.id,alicloud_vswitch.vsw1.id
  ]
  # The computing performance, number of keys, number of secrets, and number of access management operations.
  vpc_num    = "1"
  key_num    = "1000"
  secret_num = "100"
  spec       = "1000"
  # Associate the KMS instance with other VPCs. This parameter is optional.
  # If the 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 = "cn-shanghai"
  #vpc_owner_id = "119285303511****"
  #}
  #bind_vpcs {
  #vpc_id = "vpc-j6cy0l32yz9ttd7g3****"
  #vswitch_id = "vsw-3h4yrd1nz8x13ram****"
  #region_id = "cn-shanghai"
  #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"
}

Create a key in the KMS instance:

# The key specification is Aliyun_AES_256, and the key is used for encryption and decryption (ENCRYPT/DECRYPT).
resource "alicloud_kms_key" "kms_software_key_encrypt_decrypt" {
  timeouts {
    delete = "20m" # Set a timeout period for deletion.
  }
  description = "default_key_encrypt_decrypt description"
  # The usage of the key. Default value: ENCRYPT/DECRYPT. Valid value: ENCRYPT/DECRYPT, which indicates that the key is used to encrypt or decrypt data.
  key_usage = "ENCRYPT/DECRYPT"
  # The specification of the key. Default value: Aliyun_AES_256.
  key_spec = "Aliyun_AES_256"
  # The source of the key material. Default value: Aliyun_KMS. Valid values: Aliyun_KMS and EXTERNAL.
  origin = "Aliyun_KMS"
  # The ID of the KMS instance.
  # If you add this parameter, a key is created in the KMS instance. Otherwise, a default master key is created.
  dkms_instance_id = alicloud_kms_instance.default.id
  # The number of days before the CMK is deleted.
  pending_window_in_days = 7
  # The mapping of tags to assign to the resource. This is optional.
  #tags = {
      #"Environment" = "Production"
      #"Name" = "KMS-01"
      #"SupportTeam" = "PlatformEngineering"
      #"Contact" = "aliyun@test.com"
    #}
}
# The key alias is alias/kms_software_key_encrypt_decrypt, which must be unique within an Alibaba Cloud account.
resource "alicloud_kms_alias" "kms_software_key_encrypt_decrypt_alias" {
  # The alias.
  alias_name = "alias/kms_software_key_encrypt_decrypt"
  # The key ID.
  key_id = alicloud_kms_key.kms_software_key_encrypt_decrypt.id
}

Run the following command to initialize the Terraform environment.

terraform init

The following output indicates that the initialization is successful.

Initializing the backend...

Initializing provider plugins...
- Reusing previous version of hashicorp/alicloud from the dependency lock file
- Using previously-installed hashicorp/alicloud v1.231.0

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.

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

Run the following command to create the key.

terraform apply

When prompted, enter yes and press the Enter key. Wait for the command to finish. The following output indicates that the key 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

...
alicloud_kms_key.kms_software_key_encrypt_decrypt: Creating...
alicloud_kms_key.kms_software_key_encrypt_decrypt: Creation complete after 0s [id=key-shh6715c21812y8i7z***]
alicloud_kms_alias.kms_software_key_encrypt_decrypt_alias: Creating...
alicloud_kms_alias.kms_software_key_encrypt_decrypt_alias: Creation complete after 0s [id=alias/kms_secret]
...

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

Verify the results.
Run the terraform show command
Run the following command to view 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 to view the created key.

Clean up resources

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

terraform destroy

Complete example

Sample code

variable "region" {
  default = "cn-shanghai"
}

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

variable "instance_type" {
  default = "ecs.n1.tiny"
}
# 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 the CIDR block 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 another vSwitch with the CIDR block 172.16.128.0/17.
resource "alicloud_vswitch" "vsw1" {
  vpc_id     = alicloud_vpc.vpc.id
  cidr_block = "172.16.128.0/17"
  zone_id    = data.alicloud_zones.default.zones.0.id
  vswitch_name = "terraform-example-2"
}
# Create a software key management instance and start it with network parameters.
resource "alicloud_kms_instance" "default" {
  timeouts {
    delete = "20m" # Set a timeout period for deletion.
  }
  # A software key management instance.
  product_version = "3"
  vpc_id          = alicloud_vpc.vpc.id
  # Specify the zones for the KMS instance using the obtained zone IDs.
  zone_ids = [
    data.alicloud_zones.default.zones.0.id,
    data.alicloud_zones.default.zones.1.id
  ]
  # The vSwitch IDs.
  vswitch_ids = [
    alicloud_vswitch.vsw.id,alicloud_vswitch.vsw1.id
  ]
  # The computing performance, number of keys, number of secrets, and number of access management operations.
  vpc_num    = "1"
  key_num    = "1000"
  secret_num = "100"
  spec       = "1000"
  # Associate the KMS instance with other VPCs. This parameter is optional.
  # If the 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 = "cn-shanghai"
  #vpc_owner_id = "119285303511****"
  #}
  #bind_vpcs {
  #vpc_id = "vpc-j6cy0l32yz9ttd7g3****"
  #vswitch_id = "vsw-3h4yrd1nz8x13ram****"
  #region_id = "cn-shanghai"
  #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"
}

# The key specification is Aliyun_AES_256, and the key is used for encryption and decryption (ENCRYPT/DECRYPT).
resource "alicloud_kms_key" "kms_software_key_encrypt_decrypt" {
  timeouts {
    delete = "20m" # Set a timeout period for deletion.
  }
  description = "default_key_encrypt_decrypt description"
  # The usage of the key. Default value: ENCRYPT/DECRYPT. Valid value: ENCRYPT/DECRYPT, which indicates that the key is used to encrypt or decrypt data.
  key_usage = "ENCRYPT/DECRYPT"
  # The specification of the key. Default value: Aliyun_AES_256.
  key_spec = "Aliyun_AES_256"
  # The ID of the KMS instance.
  # If you add this parameter, a key is created in the KMS instance. Otherwise, a default master key is created.
  dkms_instance_id = alicloud_kms_instance.default.id
  # The number of days before the CMK is deleted.
  pending_window_in_days = 7
  # The mapping of tags to assign to the resource. This is optional.
  #tags = {
      #"Environment" = "Production"
      #"Name" = "KMS-01"
      #"SupportTeam" = "PlatformEngineering"
      #"Contact" = "aliyun@test.com"
    #}
}
# The key alias is alias/kms_software_key_encrypt_decrypt, which must be unique within an Alibaba Cloud account.
resource "alicloud_kms_alias" "kms_software_key_encrypt_decrypt_alias" {
  # The alias.
  alias_name = "alias/kms_software_key_encrypt_decrypt"
  # The key ID.
  key_id = alicloud_kms_key.kms_software_key_encrypt_decrypt.id
}