How to use Terraform to manage KMS resources - Key Management Service

Terraform is an open source tool provided by HashiCorp. Terraform allows you to preview, configure, and manage cloud infrastructures and resources in a secure and efficient manner. You can configure Terraform to automatically create and update Alibaba Cloud infrastructures and resources and perform version management. This topic describes how to use Terraform to manage Key Management Service (KMS) resources.

Prerequisites

By default, Cloud Shell is preinstalled with Terraform and configured with Alibaba Cloud account information. If you use Cloud Shell, you do not need to perform other operations. If you do not use Cloud Shell, you must install Terraform and configure your Alibaba Cloud account information.

The version of Terraform is v0.14 or later. For more information, see Install and configure Terraform in the local PC.
Note
After you install Terraform, you can run the terraform --version command to check the version of Terraform. If the version of Terraform is earlier than v0.14, install Terraform of the required version to overwrite the original version of Terraform. For more information about Terraform, see What is Terraform?
Your Alibaba Cloud account information is configured.
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.
- We recommend that you specify identity information in environment variables. The method that is used to configure environment variables varies based on the operating system. For more information, see Configure environment variables in Linux, macOS, and Windows.
```
export ALICLOUD_ACCESS_KEY="******"
export ALICLOUD_SECRET_KEY="******"
export ALICLOUD_REGION="******"
```
- You can also specify identity information in the provider section of the configuration file.
```
provider "alicloud" {
  access_key = "******"
  secret_key = "******"
  region     = "******"
}
```

Use Terraform to create a key

Create a working directory and then create the configuration files named main.tf and variables.tf in the working directory.

main.tf: This file is the main file of Terraform and defines the resources that you want to deploy.

# For more information about the alicloud_kms_key resource, visit https://registry.terraform.io/providers/aliyun/alicloud/latest/docs/resources/kms_key.
resource "alicloud_kms_key" "dkms_key" {
  description                   = "${var.description}"
  protection_level              = "${var.protection_level}"
  dkms_instance_id              = "${var.dkms_instance_id}"
}

output "dkms_key_id" {
  value = alicloud_kms_key.dkms_key.id
}

variables.tf: This file contains the variables that can be transferred to main.tf. These variables can help you customize the environment.

# The description of the key.
variable "description" {
  default = "the new dkms key"
}

# The scheduled deletion period. After the period elapses, key is deleted. During the scheduled deletion period, the key is in the Pending Deletion state. After the scheduled deletion period elapses, you cannot cancel the key deletion task. 
variable "pending_window_in_days" {
  default = "7"
}

# For an instance of the software key management type, set this parameter to SOFTWARE.
# For an instance of the hardware key management type, set this parameter to HSM.
variable "protection_level" {
  default = "SOFTWARE"
}

# The ID of your KMS instance.
variable "dkms_instance_id" {
  default = "kst-xxxxxxxxxxxxxxx"
}

Run the terraform init command to initialize the Terraform runtime environment.

Expected output:

Initializing the backend...

Initializing provider plugins...
- Finding latest version of hashicorp/alicloud...
- Installing hashicorp/alicloud v1.183.0...
- Installed hashicorp/alicloud v1.183.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.

╷
│ Warning: Additional provider information from registry
│
│ The remote registry returned warnings for registry.terraform.io/hashicorp/alicloud:
│ - For users on Terraform 0.13 or greater, this provider has moved to aliyun/alicloud. Please update your source in required_providers.
╵

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.

Run the terraform plan command to generate a resource 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:

  # alicloud_kms_key.dkms_key will be created
  + resource "alicloud_kms_key" "dkms_key" {
      ...
    }

Plan: 1 to add, 0 to change, 0 to destroy.

Changes to Outputs:
  + dkms_key_id              = (known after apply)

─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────

Note: You didn't use the -out option to save this plan, so Terraform can't guarantee to take exactly these actions if you run "terraform apply" now.

Run the terraform apply command to create the key.

Expected output:

...
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: 1 added, 0 changed, 0 destroyed.

Outputs:

dkms_key_id = "key-xxxxxxxxxxxxxxxxxx"

After the key is created, you can perform the following operations:

Query the ID of the key:

terraform output dkms_key_id

Expected output:

"key-xxxxxxxxxxxxxxxxxx"

Schedule a key deletion task:

terraform destroy

Expected output:

...
Plan: 0 to add, 0 to change, 1 to destroy.
...
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: yes
...
Destroy complete! Resources: 1 destroyed.

Use Terraform to create a secret

Create a working directory and then create the configuration files named main.tf and variables.tf in the working directory.

main.tf: This file is the main file of Terraform and defines the resources that you want to deploy.

# For more information about the alicloud_kms_secret resource, visit https://registry.terraform.io/providers/aliyun/alicloud/latest/docs/resources/kms_secret.
resource "alicloud_kms_secret" "dkms_secret" {
  secret_name                   = "secret-simple"
  description                   = "from terraform"
  secret_data                   = "${var.ENV_SECRET_DATA}"
  version_id                    = "${var.version_id}"
  encryption_key_id             = "${var.encryption_key_id}"
  dkms_instance_id              = "${var.dkms_instance_id}"
  force_delete_without_recovery = true
}

variables.tf: This file contains the variables that can be transferred to main.tf. These variables can help you customize the environment.

# The version of the secret.
variable "version_id" {
  default = "000000000001"
}

# Run the export TF_VAR_ENV_SECRET_DATA=xxxxxxxxxx command to configure the secret.
variable "ENV_SECRET_DATA" {
  default = "Secret data."
  #sensitive = true
}

variable "encryption_key_id" {
  default = "key-xxxxxxxxxxxxxxxxxx"
}

# The ID of your KMS instance.
variable "dkms_instance_id" {
  default = "kst-xxxxxxxxxxxxxxx"
}

Run the terraform init command to initialize the Terraform runtime environment.

Expected output:

Initializing the backend...

Initializing provider plugins...
- Finding latest version of hashicorp/alicloud...
- Installing hashicorp/alicloud v1.183.0...
- Installed hashicorp/alicloud v1.183.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.

╷
│ Warning: Additional provider information from registry
│
│ The remote registry returned warnings for registry.terraform.io/hashicorp/alicloud:
│ - For users on Terraform 0.13 or greater, this provider has moved to aliyun/alicloud. Please update your source in required_providers.
╵

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.

Run the terraform plan command to generate a resource 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:

  # alicloud_kms_secret.dkms_secret will be created
  + resource "alicloud_kms_secret" "dkms_secret" {
      ...
    }

Plan: 1 to add, 0 to change, 0 to destroy.

─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────

Note: You didn't use the -out option to save this plan, so Terraform can't guarantee to take exactly these actions if you run "terraform apply" now.

Run the terraform apply command to create a secret.

Expected output:

...
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: 1 added, 0 changed, 0 destroyed.

After the secret is created, you can run the following command to delete the secret:

terraform destroy

Expected output:

...
Plan: 0 to add, 0 to change, 1 to destroy.
...
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: yes
...
Destroy complete! Resources: 1 destroyed.