Step 2: Perform the migration - Key Management Service - Alibaba Cloud Documentation Center

This topic describes how to migrate resources from a KMS 1.0 instance to a KMS 3.0 instance.

Note

Migration is supported only within the same region. If you have resources in multiple regions, you must purchase a KMS 3.0 instance for each region and then migrate the resources for each region separately.

1. Determine if you have resources to migrate

Note

This method only shows keys that can be migrated. For keys that cannot be migrated, you can view the remaining keys in the legacy console after migration and contact Alibaba Cloud technical support for assistance.

Log on to the KMS 1.0 console. In the navigation pane on the left, click Migration Tool.
If the Migrate button is available, this indicates that there are keys or secrets to migrate in the current region.
Important
Data is displayed by region. Make sure to check the data for all regions to avoid overlooking any resources.
Click the numbers in the Keys Not Migrated, Migrated Keys, Secrets Not Migrated, and Migrated Secrets columns to view specific key IDs and secret names.

2. Migration procedure

Important

You can migrate a maximum of 50 keys and 50 secrets at a time. If you have more resources, you must migrate them in batches.

Single-account migration

Prepare the destination KMS instance.
- If you have not purchased a KMS instance, you must first purchase and enable one. For more information, see Purchase and enable a KMS instance.
  You should enable auto-renewal for the KMS instance. This prevents decryption failures that can occur if the instance expires and is released, which would make your application data inaccessible.
- If you already have an instance, make sure its image version meets the requirements for migration.
  - Software key management instance: If the image version is earlier than 2.9.0, upgrade the image to the latest version. For more information, see Upgrade the image version of a KMS instance.
  - Hardware key management instance: Contact Alibaba Cloud technical support to upgrade the image version.
Log on to the KMS 1.0 console and disable key and secret rotation.
Note
You cannot disable rotation in batches. You must disable rotation for each key and secret individually.

In the navigation pane on the left, click Migration Tool. Find the region that contains the resources you want to migrate and click Migrate in the Actions column. On the Migrate Resources tab, complete the configuration.

Parameter	Description
Type	The type of the destination KMS instance.
Instance	Select the destination KMS instance and set it as the default instance. After the migration, if you create a resource without specifying a KMS instance (either in the KMS 1.0 console or by not providing a KMS instance ID in an API call), the resource is created in KMS 1.0 and marked for migration. To avoid this, you must set a default instance during migration. After you set a default instance, resources created without a specified KMS instance are automatically assigned to that default instance. Note If a default instance has never been set for the current region, the Set as 3.0 Default Instance checkbox is automatically selected after you select a destination KMS instance. If a default instance has already been set for the region, the checkbox is not automatically selected. However, if you select a different KMS instance, the previous default setting is automatically overwritten. Only one default instance can be set per region.
Migration Method	Automatic Migration: Select a migration time. The migration starts automatically at the specified time. Manual Migration (Start Now): The migration starts immediately after configuration.
Migration Time	This is required only when you select Automatic Migration.
Resources	Important Before migrating, make sure your KMS instance has a sufficient quota to avoid migration failures. Manually Select Resources: Manually select resources. You can select up to 50 keys and 50 secrets at a time. You can filter resources by key ID, key alias, and secret name. Keys and Secrets: Migrate all keys and secrets at once.

Carefully read the Migration Instructions and click OK. Then, review the migration checklist and click Migrate.
You can view the migration progress in the Task Status column. When the migration is complete, a Migration Completed message is displayed.
If automatic rotation was enabled for keys and secrets before the migration, you must re-enable rotation after the migration is complete. For more information, see Key rotation and Overview of secret management.

Multi-account migration

To migrate resources from multiple Alibaba Cloud accounts to a single KMS instance, perform the following steps.

Prepare the destination KMS instance in one of the accounts.
- If you have not purchased a KMS instance, you must first purchase and enable one. For more information, see Purchase and enable a KMS instance.
  You should enable auto-renewal for the KMS instance. This prevents decryption failures that can occur if the instance expires and is released, which would make your application data inaccessible.
- If you already have an instance, make sure its image version meets the requirements for migration.
  - Software key management instance: If the image version is earlier than 2.9.0, upgrade the image to the latest version. For more information, see Upgrade the image version of a KMS instance.
  - Hardware key management instance: Contact Alibaba Cloud technical support to upgrade the image version.
Share the KMS instance with the other Alibaba Cloud accounts. For more information, see Steps 1 to 3 in Share a KMS instance across multiple accounts.
Important
Sharing is supported only within a resource directory. The resource owner and the principal must belong to the same enterprise that has completed identity verification.
Log on to each Alibaba Cloud account and migrate its resources to the shared KMS instance. The procedure is the same as that for a single-account migration.

3. Post-migration operations

Important

After the migration, KMS applies a default policy to the migrated keys and secrets. For more information, see Overview of key policies and Overview of secret policies.

Log on to the KMS 3.0 console to view and confirm the migrated resources.
- Service keys
  1. Go to the Keys page and select a region from the top menu bar.
  2. Click the Default Keys tab. Verify that your service keys are listed and that the Key Usage column is set to Service Key.
- Customer master keys
  1. Go to the Keys page and select a region from the menu bar at the top.
  2. Click the Customer Master Keys tab and verify that the migrated customer master keys are displayed.
- Secrets
  1. Go to the Secrets page and select a region from the menu bar at the top.
  2. Select the KMS instance and confirm that the migrated secrets are listed.
If you use Terraform to manage KMS resources, you must modify the Terraform configuration. For more information, see Modify configurations after migration in a Terraform scenario.

4. Migration monitoring

To ensure a smooth, observable, and traceable key migration, you should monitor the shared and dedicated gateways before, during, and after the migration. You can use CloudMonitor, Simple Log Service (SLS), and ActionTrail for comprehensive monitoring. The following sections describe key observation points and recommended actions.

Before migration: Observe the shared gateway dashboard
Before the key migration is complete and before you switch the client Endpoint, all KMS requests are still processed by the shared gateway. At this stage, you should focus on the stability and performance of the shared gateway.
- Observation goal: Confirm that the migration does not cause abnormal loads or errors on the shared gateway.
- Metrics to observe:
  - Request latency: Check for any significant increase.
  - Error code distribution (such as 4xx and 5xx): Confirm that there is no sudden increase in abnormal errors.
  - QPS/TPS trends: Compare traffic before and after the migration to ensure consistency. This helps prevent request surges or interruptions caused by incorrect operations.
- How to view:
  - Method 1: Log on to the KMS 3.0 console. On the Overview page, check metrics such as request latency and error codes on the Shared gateway dashboard.
  - Method 2: Log on to the CloudMonitor console. In the Cloud Service Monitoring section, search for Key Management Service to view the Shared gateway dashboard.
Note
Record baseline metrics before the migration to use as a reference for comparison.

After migration: Observe the shared gateway and dedicated gateway dashboards simultaneously

Before switching the Endpoint: Continue to observe the shared gateway. Although the keys have been migrated to a dedicated instance, requests are still routed through the shared gateway until you switch the client Endpoint. The shared gateway transparently forwards these requests to the backend dedicated instance.

After switching the Endpoint: Observe the shared and dedicated gateways simultaneously. After the client completes the Endpoint switch, requests directly access the dedicated instance through the dedicated gateway. At this point, you must monitor both gateways:

Gateway type	Key observation points	How to view
Dedicated gateway	Error codes Changes in request latency Whether QPS meets expectations	CloudMonitor: KMS dedicated gateway dashboard
Shared gateway	Whether requests from the original service have been fully switched Whether there are any remaining requests or abnormal calls	Observe the shared gateway dashboard for the corresponding region

Note

Criteria for identifying anomalies:

If the dedicated gateway reports a high number of throttling errors, you may need to adjust the instance type or throttling policy.
If the shared gateway still receives a high frequency of requests, this indicates that some clients have not completed the Endpoint switch. You must investigate the issue.

Log-level observation: Analyze detailed access logs using SLS
To achieve more granular request tracking and problem diagnosis, enable the following log collection features:
- Dedicated gateway access logs:
  - You can purchase the log analysis value-added service for dedicated gateways to automatically deliver logs to Simple Log Service (SLS).
  - You can query and analyze logs by fields such as key ID, Alibaba Cloud account, API operation, and response status code.
- Shared gateway detailed access logs:
  - Enable ActionTrail and deliver event traces to a specified SLS Logstore.
  - Analyze specific request behaviors by querying for conditions such as EventName = "Decrypt" and ResourceType = "KMS".
  - Use the ErrorCode field to determine the cause of failures, such as insufficient permissions or a key that does not exist.

Recommended monitoring strategy

Phase	Monitoring focus	Tool
Before migration	Shared gateway stability	CloudMonitor dashboard
During switchover	Request success rate, sudden changes in latency	Real-time monitoring + SLS alerting
After migration	Dedicated gateway health status	Dedicated gateway dashboard + SLS logs
Throughout the process	Abnormal error code trends	ActionTrail + SLS aggregation analysis