Step 2: Migration - Key Management Service - Alibaba Cloud Documentation Center

This topic describes the steps to migrate resources from the shared version of Key Management Service (KMS, also called KMS 1.0) to a KMS instance (also called KMS 3.0).

Quickly check resources to migrate

Note

This method only identifies migratable keys. For keys that are not supported for migration, create a new key in the KMS 3.0 instance and use it in the new KMS console directly.

Log on to the old KMS console and choose Migration Tool in the left-side navigation pane.
Use one of the following methods to check if there are resources that need migration:
Important
The data is displayed by region, so review all regions to ensure that you do not miss any resources that need to be migrated.
- Method 1: If the data in the red box is greater than 0, this indicates there are keys or secrets to migrate in that region.
- Method 2: If the Migrate in the Actions column is enabled, this indicates there are keys or secrets to migrate in that region.

Migrate resources

If your business operates in a single Alibaba Cloud account scenario, perform the migration steps in Migrate resources within a single Alibaba Cloud account.

If your business operates in multiple Alibaba Cloud accounts, perform the migration steps in Migrate resources from multiple accounts to a single KMS instance.

Important

When preparing KMS 3.0 instances, ensure that they have sufficient key and secret quotas to prevent migration failures caused by insufficient quotas.
Migration is only supported within the same region. If you have resources in multiple regions, purchase KMS 3.0 instances for each region separately and then perform the migration by region.

Migrate resources within a single Alibaba Cloud account

Prepare the target KMS 3.0 instance using your Alibaba Cloud account that includes KMS 1.0 resources.
- If you have not yet purchased a KMS instance, purchase and enable a KMS instance.
  We recommend that you enable auto-renewal for the KMS instance to avoid application data decryption failures due to instance expiration.
- If you already enabled an instance, check if the instance's image version meets the migration requirements.
  - For software key management instances: If the image version is below 2.9.0, upgrade to the latest version.
  - For hardware key management instances: contact your account manager to upgrade the image version.
If your keys and secrets have automatic rotation enabled, log on to the old KMS console, disable automatic rotation to ensure version consistency before migration.
To disable key rotation, see Automatic key rotation.
To disable secret rotation, see Manage dynamic ApsaraDB RDS secrets, Manage dynamic RAM secrets or Manage dynamic ECS secrets.
Note
Key and secret rotation cannot be disabled in bulk. Rotation must be disabled for each key and secret individually.

Choose Migration Tool in the left-side navigation pane. Find the region where the resources to be migrated are located, click Migrate in the Actions column, and configure the parameters on the Migrate Resources panel.

Important

A maximum of 50 keys and 50 secrets can be migrated per operation. If you have many resources, migrate them in batches.

Parameter	Description
Type	Select the target KMS instance type.
Instance	Select the target KMS instance.
Migration Method	Automatic Migration: Set the migration time. The system automatically migrates the resources at the specified time. Manual Migration (Start Now): The system migrates the resources immediately after you complete the configuration.
Migration Time	This parameter is required only when you set Migration Method to Automatic Migration.
Resources	Manually Select Resources: Manually select the keys and secrets to be migrated. You can select a total of up to 50 keys and secrets. Keys and Secrets: Migrate all keys and secrets.

Review Migration Instructions carefully and select all items, then click OK. After verifying the migration checklist, click Migrate.
You can monitor the migration progress in the Task Status column. When the migration is completed, the Task Status becomes Completed. Note that the Completed only indicates the migration task is completed. Click Results in the Task Status column to check the migration details.
If keys and secrets have automatic rotation enabled before migration, enable rotation after migration. For more information, see Key rotation and Secret rotation.

Migrate resources from multiple accounts to a single KMS instance

Prepare the target KMS 3.0 instance using a single Alibaba Cloud account.
- If you have not yet purchased a KMS instance, purchase and enable a KMS instance.
  We recommend that you enable auto-renewal for the KMS instance to avoid application data decryption failures caused by instance expiration.
- If you already enabled an instance, check if the instance's image version meets the migration requirements.
  - For software key management instances: If the image version is below 2.9.0, upgrade to the latest version.
  - For hardware key management instances: contact your account manager to upgrade the image version.
Share the KMS instance with other Alibaba Cloud accounts that include resources to be migrated. For more information, see Steps 1 to 3 in Share a KMS instance across multiple Alibaba Cloud accounts.
Important
KMS 3.0 instances can be shared only within a resource directory. The principals must belong to the same enterprise entity as the resource owner of the KMS 3.0 instance. The enterprise entity must pass real-name verification.
Migrate the resources of each account to the KMS 3.0 instance.
Log on to each account, and perform Steps 2 to 4 in Migrate resources within a single Alibaba Cloud account.

Verify resources

After migration, a default policy for the keys and secrets is set. For more information, see Key policy and Secret policy.

Log on to the new KMS console, then check and confirm the migrated resources.
1. Confirm service keys.
  1. In the left-side navigation pane, click Keys, and select the region in the top navigation bar.
  2. Click the Default Key tab. In the Key Usage column, you can find the Service Key that has been migrated.
2. Confirm the customer master key by switching to the Keys tab.
  You can find the detailed information about the customer master key that has been migrated, such as alias, key specifications and purpose.
3. Confirm secrets.
  1. In the left-side navigation pane, click Secrets, and select the KMS instance.
    You can find the detailed information about the secrets that have been migrated, such as name and secret type.

If your KMS 1.0 is Terraform-managed, Terraform configuration changes are required due to the instance ID attribute added. Otherwise, the migration will fail.
For more information, see Post-migration configuration changes for Terraform-managed KMS.