How to update Terraform configurations after migration - Key Management Service

This topic describes how to update your Terraform configuration after a resource migration in a Terraform environment.

Why update Terraform configuration

After migration, resource attributes change in the following ways:

Migrating a Customer Master Key (CMK) or a secret from a shared Key Management Service (KMS) 1.0 instance to a KMS 3.0 instance associates the resource with the new instance. This adds a KMS instance ID attribute to the resource.
If you migrate a key with an HSM protection level to a software key management instance, its protection level changes to SOFTWARE.

When Terraform detects that your configuration files do not match the actual state of your infrastructure, it creates an execution plan to align them. This discrepancy can cause Terraform to destroy the migrated CMK or secret and create a new one. To prevent this, you must update your Terraform configuration after the migration is complete.

Terraform update solutions

KMS offers two solutions to update your Terraform configuration. Choose the solution that best fits your use case.

Criteria	Solution 1: Add ignore_changes (recommended)	Solution 2: Add dkms_instance_id
How it works	Add the `ignore_changes` argument to the `lifecycle` block. This instructs Terraform to ignore attribute changes caused by the migration during `plan` and `apply` operations.	Explicitly declare the `dkms_instance_id` in the resource configuration to match the actual state of the resource.
Handles `dkms_instance_id` change	Yes	Yes
Handles `protection_level` change	Yes	No
Code modification	Avoids changes to business logic code.	Requires changes to business logic code.
Version compatibility	Works with Terraform provider versions 1.235.0 and earlier. Note For Terraform versions 1.235.0 and later, you no longer need to ignore `dkms_instance_id`. You can remove `dkms_instance_id` from the `ignore_changes` parameter.	Works with all provider versions.
Use cases	Migrating a key from an HSM to a software key management instance, which changes the protection level to `SOFTWARE`. When modifying business logic code is difficult.	Scenarios where the protection level does not change. When you need to keep your Terraform configuration perfectly synchronized with the actual resource state.

Solution 1: Add ignore_changes

For the alicloud_kms_key resource, perform the following steps:

Add the ignore_changes = [dkms_instance_id,automatic_rotation,rotation_interval,protection_level] statement.
If key rotation was disabled before migration, enable it after the migration is complete. For more information, see key rotation.
Set a default key policy. To create a custom policy, see Key policy overview.

The following example enables key rotation with a 90-day interval and sets a default key policy. Adjust the configuration to meet your business requirements. For details about each parameter, see alicloud_kms_key.

resource "alicloud_kms_key" "default_key_encrypt_decrypt" {
 #   add this
  lifecycle {
    ignore_changes = [dkms_instance_id,automatic_rotation,rotation_interval,protection_level]
  }
  automatic_rotation = "Enabled"
  rotation_interval = "90d"
  policy = <<EOF
    {
        "Statement": [
            {
                "Action": [
                    "kms:*"
                ],
                "Effect": "Allow",
                "Principal": {
                    "RAM": [
                        "acs:ram::5135****76002605:*"
                    ]
                },
                "Resource": [
                    "*"
                ],
                "Sid": "kms default key policy"
            }
        ],
        "Version": "1"
    }
  EOF
  #   end of add
  description = "test tf"
  key_usage = "ENCRYPT/DECRYPT"
  key_spec = "Aliyun_AES_256"
  origin = "Aliyun_KMS"
  pending_window_in_days = 7
  tags = {
      "Environment" = "test"
      "Name" = "KMS-01"
      "SupportTeam" = "PlatformEngineering"
      "Contact" = "group@example.com"
    }
}

For the alicloud_kms_secret resource, perform the following steps:

Add the ignore_changes = [dkms_instance_id] statement.
If secret rotation was disabled before migration, enable it after the migration is complete.
Set a default secret policy. To create a custom policy, see Secret policy overview.

In the following example, secret rotation is disabled, and a default secret policy is set. Adjust the configuration to meet your business requirements. For details about each parameter, see alicloud_kms_secret.

resource "alicloud_kms_secret" "kms_secret_general" {
  #   add this
 lifecycle {
    ignore_changes = [dkms_instance_id]
      }
 enable_automatic_rotation = false   
 policy = <<EOF
    {
        "Statement": [
            {
                "Action": [
                    "kms:*"
                ],
                "Effect": "Allow",
                "Principal": {
                    "RAM": [
                        "acs:ram::5135****76002605:*"
                    ]
                },
                "Resource": [
                    "*"
                ],
                "Sid": "kms default secret policy"
            }
        ],
        "Version": "1"
    }
  EOF     
  #   end of add
  secret_name = "kms_secret_general1"
  description = "secret_data_kms_secret_general"
  secret_type = "Generic"
  force_delete_without_recovery = true
  encryption_key_id = alicloud_kms_key.default_key_encrypt_decrypt.id
  version_id = "v1"
  secret_data_type ="text"
  secret_data = "secret_data_kms_secret_general1"
}

Solution 2: Add dkms_instance_id

This example shows how to update your configuration after migrating the CMK fecbd43a-*****-9c051c8cc26d to the KMS instance kst-hkk66e****boq8qsxxgxd.

In the main.tf file in the root directory, add the following code.

In locals, add dkms_instance_id = var.use_existing_key == true || alicloud_kms_key.kms.0.dkms_instance_id != "" ? alicloud_kms_key.kms.0.dkms_instance_id : null.
In "alicloud_kms_key", add dkms_instance_id = var.dkms_instance_id.
In "alicloud_kms_secret", add dkms_instance_id = var.dkms_instance_id.

Example:

locals {
  this_kms_key_id    = var.use_existing_key == true || var.existing_key_id != "" ? var.existing_key_id : concat(alicloud_kms_key.kms.*.id, [""])[0]
  dkms_instance_id    = var.use_existing_key == true || alicloud_kms_key.kms.0.dkms_instance_id != "" ? alicloud_kms_key.kms.0.dkms_instance_id : null
  policy    = var.use_existing_key == true || alicloud_kms_key.kms.0.policy != "" ? alicloud_kms_key.kms.0.policy : null
  automatic_rotation= var.use_existing_key == true || alicloud_kms_key.kms.0.automatic_rotation != "" ? alicloud_kms_key.kms.0.automatic_rotation : null
  rotation_interval= var.automatic_rotation == "Enabled" || alicloud_kms_key.kms.0.rotation_interval != "" ? alicloud_kms_key.kms.0.rotation_interval : null
  secret_name = var.secret == true ||alicloud_kms_secret.kms.0.secret_name != "" ? alicloud_kms_secret.kms.0.secret_name : null
  secret_type = var.secret == true ||alicloud_kms_secret.kms.0.secret_type != "" ? alicloud_kms_secret.kms.0.secret_type : null
  version_id = var.secret == true ||alicloud_kms_secret.kms.0.version_id != "" ? alicloud_kms_secret.kms.0.version_id : null
  force_delete_without_recovery = var.secret == true ||alicloud_kms_secret.kms.0.force_delete_without_recovery != "" ? alicloud_kms_secret.kms.0.force_delete_without_recovery : null
  secret_data = var.secret == true ||alicloud_kms_secret.kms.0.secret_data != "" ? alicloud_kms_secret.kms.0.secret_data : null
  secret_data_type = var.secret == true ||alicloud_kms_secret.kms.0.secret_data_type != "" ? alicloud_kms_secret.kms.0.secret_data_type : null
  enable_automatic_rotation = var.secret == true ||alicloud_kms_secret.kms.0.enable_automatic_rotation != "" ? alicloud_kms_secret.kms.0.enable_automatic_rotation : null
}
resource "alicloud_kms_key" "kms" {
  count                   = var.use_existing_key == true ? 0 : var.create_kms ? 1 : 0
  description             = var.description
  key_usage               = var.key_usage
  pending_window_in_days = var.pending_window_in_days
  status              = var.status
  policy = var.policy
  automatic_rotation = var.automatic_rotation
  rotation_interval = var.rotation_interval
  #   add this
  dkms_instance_id    = var.dkms_instance_id
  #   end of add
}
resource "alicloud_kms_secret" "kms" {
  count              = var.existing_key_id != "" ? var.existing_key_id : var.encrypt ? 1 : 0
  secret_name                   = var.secret_name
  encryption_key_id             = concat(alicloud_kms_key.kms.*.id, [""])[0]
  secret_type                   = var.secret_type
  version_id                    = var.version_id
  force_delete_without_recovery = var.force_delete_without_recovery
  #   add this
  dkms_instance_id    = var.dkms_instance_id
  #   end of add
  secret_data = var.secret_data
  secret_data_type =var.secret_data_type
  enable_automatic_rotation = var.enable_automatic_rotation
}

In the root directory's variable.tf file, define the dkms_instance_id variable.

Important

The value of default must be "" or null.

# module default variable
variable "dkms_instance_id" {
  description = "The ID of the KMS instance."
  type        = string
  default     = ""
}

# variables.tf
variable "create_kms" {
}
variable "use_existing_key" {
  description = "Whether to create key. If false, you can speci..."
  type        = bool
  default     = false
}
variable "dkms_instance_id" {
  description = "The ID of the KMS instance."
  type        = string
  default     = ""
}
variable "policy" {
  description = " The content of the key policy. The value is i..."
  type        = string
  default     = ""
}
variable "automatic_rotation" {
  description = "Specifies whether to enable automatic key rota..."
  type        = string
  default     = "Disabled"
}
# main.tf
locals {
  this_kms_key_id    = var.use_existing_key == true || var.existing_key_id != "" ? var.existing_key_id : concat(alicloud_kms_key.kms.*.id, [""])[0]
  dkms_instance_id   = var.use_existing_key == true || alicloud_kms_key.kms.0.dkms_instance_id != "" ? alicloud_kms_key.kms.0.dkms_instance_id : null
  policy      = var.use_existing_key == true || alicloud_kms_key.kms.0.policy != "" ? alicloud_kms_key.kms.0.policy : null
  automatic_rotation= var.use_existing_key == true || alicloud_kms_key.kms.0.automatic_rotation != "" ? alicloud_kms_key.kms.0.automatic_rotation : null
  rotation_interval= var.use_existing_key == true || alicloud_kms_key.kms.0.rotation_interval != "" ? alicloud_kms_key.kms.0.rotation_interval : null
  ciphertext_blob   = var.decrypt == true || alicloud_kms_ciphertext.kms.0.ciphertext_blob != "" ? alicloud_kms_ciphertext.kms.0.ciphertext_blob : null
  encryption_context = var.decrypt == true || alicloud_kms_ciphertext.kms.0.encryption_context != "" ? alicloud_kms_ciphertext.kms.0.encryption_context : null
  plaintext = var.decrypt == true ||alicloud_kms_ciphertext.kms.0.plaintext != "" ? alicloud_kms_ciphertext.kms.0.plaintext : null
}
resource "alicloud_kms_key" "kms" {
  count                  = var.use_existing_key == true ? 0 : var.create_kms ? 1 : 0
  description            = var.description
  key_usage              = var.key_usage
  pending_window_in_days = var.pending_window_in_days
  status                 = var.status
  policy = var.policy
  automatic_rotation = var.automatic_rotation
  rotation_interval = var.rotation_interval
  #  add this
  dkms_instance_id       = var.dkms_instance_id
  #  end of add
}

In the module for your key, add the instance ID, set the key policy, and configure key rotation based on your requirements.

Rotation interval: The example uses a 90-day interval. Modify this value as needed.
KMS instance ID: An example is kst-hkk66e****boq8qsxxgxd. Replace the example with your actual ID.
Key policy: The example provides a default policy. To create a custom policy, see Key policy overview.

  automatic_rotation = "Enabled"
  rotation_interval = "90d"
  dkms_instance_id        = "kst-hkk66e****boq8qsxxgxd"
  policy = <<EOF
    {
        "Statement": [
            {
                "Action": [
                    "kms:*"
                ],
                "Effect": "Allow",
                "Principal": {
                    "RAM": [
                        "acs:ram::5135****76002605:*"
                    ]
                },
                "Resource": [
                    "*"
                ],
                "Sid": "kms default key policy"
            }
        ],
        "Version": "1"
    }
  EOF

# In examples/complete/main.tf (module call)
module "kms" {
  source = "../.." 
  region = var.region
  profile = var.profile
  #key
  description            = "Hello_KMS"
  pending_window_in_days = "7"
  status                 = "Enabled"
  automatic_rotation = "Enabled"
  rotation_interval = "90d"
  dkms_instance_id    = "kst-hkk66exxx"
  policy = <<EOF
  {
    "Statement": [
      {
        "Action": [
          "kms:*"
        ]
      }
    ],
    "Version": "1"
  }
  EOF
}
# In main.tf (resource block)
locals {
  rotation_interval= var.automatic_rotation == "Enabled" || ali...
  ciphertext_blob    = var.decrypt == true || alicloud_kms_cip...
  encryption_context = var.decrypt == true || alicloud_kms_cip...
  plaintext = var.decrypt == true ||alicloud_kms...
}
resource "alicloud_kms_key" "kms" {
  count              = var.use_existing_key == true ? 0
  description        = var.description
  key_usage          = var.key_usage
  pending_window_in_days = var.pending_window_in_days
  status             = var.status
  policy             = var.policy
  automatic_rotation = var.automatic_rotation
  rotation_interval  = var.rotation_interval
  # add this
  dkms_instance_id   = var.dkms_instance_id
  lifecycle {
    # ...
  }
}

In the module for your secret, add the instance ID, set the secret policy, and configure rotation based on your requirements.

Rotation interval: Rotation is not enabled in the example. Modify this setting as needed.
KMS instance ID: An example is kst-hkk66e****boq8qsxxgxd. Replace it with your actual instance ID.

Secret policy: The example provides a default policy. To create a custom policy, see Secret policy overview.

 #secret
  secret_data = "secret_data_kms_secret_general1"
  secret_name = "kms_secret_general1"
  version_id = "v1"
  secret_data_type ="text"
  secret_type = "Generic"
  enable_automatic_rotation = false
  dkms_instance_id        = "kst-hkk66e****boq8qsxxgxd"
  policy = <<EOF
    {
        "Statement": [
            {
                "Action": [
                    "kms:*"
                ],
                "Effect": "Allow",
                "Principal": {
                    "RAM": [
                        "acs:ram::5135****76002605:*"
                    ]
                },
                "Resource": [
                    "*"
                ],
                "Sid": "kms default secret policy"
            }
        ],
        "Version": "1"
    }
  EOF   
  force_delete_without_recovery = true