How to update Terraform configurations after migration - Key Management Service

When you migrate shared Key Management Service (KMS 1.0) to KMS 3.0, each key and secret becomes associated with a specific KMS instance, adding a dkms_instance_id attribute. If you manage KMS resources with Terraform, update your configurations before running terraform plan or terraform apply. Without the update, Terraform detects the new attribute, destroys your migrated Customer Master Keys (CMKs) and secrets, and recreates them — causing data loss.

Choose a solution

Situation	Recommended solution
Minimal changes needed; Terraform does not need to track the KMS instance association	Solution 1: Keep existing configurations
Terraform configurations should fully reflect the KMS instance association after migration	Solution 2: Adopt new configurations

Solution 1: Keep existing configurations

Add a lifecycle block with ignore_changes to each alicloud_kms_key and alicloud_kms_secret resource. This tells Terraform to ignore the dkms_instance_id attribute during plan and apply operations, preventing the resources from being destroyed and recreated.

Important

This solution works with Terraform provider version 1.235.0 and earlier. For later versions, remove dkms_instance_id from the ignore_changes list.

If you are migrating keys from hardware to software protection level, also add protection_level to the ignore_changes list: ignore_changes = [dkms_instance_id, automatic_rotation, rotation_interval, protection_level].

Steps

Add the following lifecycle block to each alicloud_kms_key and alicloud_kms_secret resource:

lifecycle {
  ignore_changes = [dkms_instance_id, automatic_rotation, rotation_interval]
}

If rotation was disabled on any keys or secrets before migration, re-enable it after migration. Skipping this step leaves rotation permanently disabled on affected resources.
- Key rotation
- Secret rotation
Configure the default policy for your keys and secrets. Without a policy, access to the resources defaults to the account-level RAM policy only.
- Configure a key policy
- Configure a secret policy

Example: alicloud_kms_key

The following example enables key rotation with a 90-day interval and sets a default key policy. Lines marked with # Add this are the new additions. For all supported parameters, see alicloud_kms_key.

resource "alicloud_kms_key" "default_key_encrypt_decrypt" {

  # Add this
  lifecycle {
    ignore_changes = [dkms_instance_id, automatic_rotation, rotation_interval]
  }
  # End of added block

  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

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

Example: alicloud_kms_secret

The following example disables secret rotation and sets a default secret policy. Lines marked with # Add this are the new additions. For all supported parameters, 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 added block

  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: Adopt new configurations

Add dkms_instance_id as an explicit argument in your Terraform configurations. Terraform reads the instance ID from the migrated resources and correctly associates the alicloud_kms_key and alicloud_kms_secret resources with the KMS 3.0 instance.

Steps

Update main.tf in the root directory with three additions: The following example shows all three additions in context. Lines marked with # Add this are the new additions:

In the locals block, add: ``hcl 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 the alicloud_kms_key resource, add: ``hcl dkms_instance_id = var.dkms_instance_id ``
In the alicloud_kms_secret resource, add: ``hcl dkms_instance_id = var.dkms_instance_id ``

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]
  # Add this
  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
  # End of add
  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
}

Define the dkms_instance_id variable in variable.tf in the root directory.
Important
Set the default value to either "" (empty string) or null. Any other default value causes Terraform to attempt binding all existing keys and secrets to a non-existent instance.
```
# Module default variable
variable "dkms_instance_id" {
  description = "The ID of the KMS instance."
  type        = string
  default     = ""
}
```

In the key module, set the instance ID, configure the key policy, and enable rotation as needed. The following example uses KMS instance kst-hkk66e****boq8qsxxgxd, enables rotation with a 90-day interval, and sets a default key policy. For custom key policies, see Key policy overview. Adjust the values to match your setup.

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 the secret module, set the instance ID, configure the secret policy, and enable rotation as needed. The following example uses KMS instance kst-hkk66e****boq8qsxxgxd, disables rotation, and sets a default secret policy. For custom secret policies, see Secret policy overview. Adjust the values to match your setup.

# Secret configuration
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"
force_delete_without_recovery = true
policy = <<EOF
  {
      "Statement": [
          {
              "Action": [
                  "kms:*"
              ],
              "Effect": "Allow",
              "Principal": {
                  "RAM": [
                      "acs:ram::5135****76002605:*"
                  ]
              },
              "Resource": [
                  "*"
              ],
              "Sid": "kms default secret policy"
          }
      ],
      "Version": "1"
  }
EOF

Key Management Service:Update Terraform configurations after migration

Choose a solution

Solution 1: Keep existing configurations

Steps

Example: alicloud_kms_key

Example: alicloud_kms_secret

Solution 2: Adopt new configurations

Steps

What's next