DocsICP FilingConsole
官方文档
首页

Step 2: Perform migration

更新时间：
复制 MD 格式
产品详情
我的收藏

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 in each region separately.

1. Check for 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.

  1. Log on to the KMS 1.0 console. In the left-side navigation pane, click Migration Tool.

  2. If the Migrate button is available, it indicates that you have 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.

    On the Migration Information page, review the table for the number of keys and secrets in each region, including the columns for Keys not migrated, Migrated keys, Secrets not migrated, and Migrated secrets, as well as the task status. In the Actions column for the target region, click Migrate.

  3. 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 than this, migrate them in batches.

Single-account migration

  1. Prepare the destination KMS instance.

    • If you have not purchased a KMS instance, purchase and enable one first. For more information, see Purchase and enable a KMS instance.

      We recommend that you enable auto-renewal for the KMS instance. This prevents the instance from expiring and being released, which would cause decryption failures and make your application data inaccessible.

    • If you already have an instance, make sure its image version meets the migration requirements.

      • For a 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.

      • For a hardware key management instance, contact Alibaba Cloud technical support to upgrade the image version.

  2. 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 individually.

    In the navigation pane on the left, click Customer master keys. Go to the details page of the target key. In the key versions section, click Set rotation policy and disable automatic rotation.

    In the navigation pane on the left, click Secrets. Go to the details page of the secret and click Set rotation policy in the upper-right corner to disable rotation.

  3. In the navigation pane on the left, click Migration Tool. Find the region that contains the resources to migrate and click Migrate in the Actions column. On the Resources tab, configure the parameters.

    Parameter

    Description

    Type

    The type of the destination KMS instance.

    Instance

    Select the destination KMS instance and set it as the default instance.

    After 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 parameter is required only if you select Automatic Migration.

    Resources
    Important

    Before migrating, make sure your KMS instance has a sufficient quota to avoid migration failures.

    • Manually Select Resources: Select the resources to migrate. You can select a maximum of 50 keys and 50 secrets at a time. You can filter resources by key ID, key alias, and secret name.

    • Keys and Secrets: Migrates all keys and secrets that are currently pending migration.

  4. Carefully read the Migration Instructions, click OK, review the migration checklist, and then click Migrate.

    Note

    You can view the migration progress in the Task Status column. When the migration is complete, a Migration Completed message is displayed.

  5. If automatic rotation was enabled for keys and secrets before the migration, you must re-enable rotation after the migration. 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.

  1. Prepare the destination KMS instance in one of the accounts.

    • If you have not purchased a KMS instance, purchase and enable one first. For more information, see Purchase and enable a KMS instance.

      We recommend that you enable auto-renewal for the KMS instance. This prevents the instance from expiring and being released, which would cause decryption failures and make your application data inaccessible.

    • If you already have an instance, make sure its image version meets the migration requirements.

      • For a 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.

      • For a hardware key management instance, contact Alibaba Cloud technical support to upgrade the image version.

  2. 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, and both the resource owner and the principal must belong to the same verified enterprise.

  3. Log on to each Alibaba Cloud account and migrate its resources to the KMS instance. The procedure is the same as that for a single-account migration.

HSM BYOK migration

Usage notes

Migration of HSM BYOK is supported only in mainland China regions.

Procedure

  1. Log on to the KMS 1.0 console. In the navigation pane on the left, click Migration Tool to open the Migration Task Information page. Find the region where the key to be migrated is located and click the number in the Unmigrated HSM BYOKs column.

  2. On the Unmigrated HSM BYOKs page, find the HSM BYOK key that you want to migrate and click Import Wrapped Key Material in the Actions column.

  3. Configure public key and token information: On the import key material page, configure the following parameters, and then click Next.

    Parameter

    Description

    Public Key Type

    Select the type of public key used to encrypt the key material. The following option is supported:

    • RSA_2048: Use an RSA 2048-bit public key.

    Encryption Algorithm

    Select the encryption algorithm. The following options are supported:

    • RSAES_OAEP_SHA_256 (Recommended): Uses RSA OAEP padding and the SHA-256 hash algorithm.

    • RSAES_PKCS1_V1_5: Uses RSA PKCS#1 v1.5 padding.

    Wrapping Key Format

    Select the format of the wrapping key to be downloaded. Supported formats are der (default) and pem.

  4. Download the wrapping public key and import token: Importing key material requires a wrapping public key and an import token. The wrapping public key encrypts the key material to protect it during import, while the import token authorizes the process.

    • Public Key Format:

      • DER Format: The downloaded file is named WrappingPublicKey**.bin by default.

      • PEM Format: The downloaded file is named WrappingPublicKey**.pem by default.

    • Import Token: The downloaded file is named ImportToken***.txt by default.

      Important

      • An import token is valid for 24 hours and can be reused within this period. After it expires, you must obtain a new import token and public key.

      • The wrapping public key and the import token must be used as a pair. You cannot use a wrapping public key from one download with an import token from another.

  5. Encrypt the key material with the wrapping public key: This section uses OpenSSL to generate key material with the RSA_2048 algorithm as an example.

    1. Create an RSA_2048 private key for the target asymmetric key and convert the private key to PKCS#8 format.

      openssl genrsa -out TakPrivPkcs1.pem 2048
openssl pkcs8 -topk8 -inform PEM -in TakPrivPkcs1.pem -outform der -nocrypt -out TakPrivPkcs8.bin

    2. Create an ephemeral session key (ESK) using the AES_256 algorithm.

      openssl rand -out EskAes256.bin 32

    3. Encrypt the ephemeral session key (ESK) with the imported wrapping key's public key (IWKpub) to create the ciphertext of the ephemeral session key (Cipher(ESK)). Use RSAES OAEP standard encryption with MGF1 and SHA256 as the hash algorithm.

      openssl pkeyutl -encrypt -pubin -inkey PublicKey.pem  -in EskAes256.bin  -pkeyopt \
rsa_padding_mode:oaep -pkeyopt rsa_oaep_md:sha256 -pkeyopt rsa_mgf1_md:sha256 -out \
CipherEsk.bin
      Note

      Replace PublicKey.pem with the name of the public key file you downloaded from the KMS console.

    4. Encrypt the target asymmetric key's private key (TAKpriv) with the ephemeral session key (ESK) to generate the ciphertext of the private key (Cipher(TAKpriv)). Use ECB mode and PKCS#7 padding.

      xxd -l 32  -c 32 -ps EskAes256.bin | xargs -I {} openssl enc  -aes-256-ecb -e  -K {} -in \ 
TakPrivPkcs8.bin -nosalt -out CipherTakPriv.bin

    5. Concatenate the resulting data in the format Cipher(ESK) || Cipher(TAKpriv) and then Base64-encode it.

      cat CipherEsk.bin CipherTakPriv.bin > EncryptedKeyMaterial.bin
openssl enc -e -base64 -A -in EncryptedKeyMaterial.bin -out EncryptedKeyMaterial_base64.txt
      Note

      EncryptedKeyMaterial_base64.txt is the key material file that can be imported into KMS.

  6. Import the migration key material: On the import key material page, configure the following parameters, and then click OK.

    Important

    The key material for migration is valid for 21 days. If the migration is not performed within this period, you must re-import the key material.

    Parameter

    Description

    Key Material Format

    Select the format of the key material to be uploaded. Supported formats are base64 (default) and bin.

    Wrapped Key Material

    Upload the key material file encrypted with the wrapping public key.

    Import Token

    Upload the import token file that you downloaded in Step 4.

    Set Expiration Time

    Set an expiration time for the key material. The following options are supported:

    • Never expires (Default): The key material never expires.

    • Custom: Set a custom expiration time for the key material. The key material is deleted at 00:00 (UTC+8) on the specified date.

  7. Perform the migration: Return to the Migration Task Information page, find the region where the target HSM BYOK is located, and click Migrate in the Actions column. On the Resources tab, configure the parameters.

    • Type: Hardware Management Instance.

    • Resources: Select Manually select resources, and then select the target HSM BYOK key.Resource Name

Troubleshooting

  • "current hardware BYOK key was not imported for migration": This indicates that the migration key material has not yet been imported for the HSM BYOK key. You must first complete the key material import procedure described in this topic.

  • "current hardware BYOK key material is expired, please reimport": This indicates that the migration key material has expired because its 21-day validity period has passed. You must re-import the key material.

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.

  1. 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 top menu bar.

      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 top menu bar.

      2. Select the KMS instance and confirm that the migrated secrets are listed. Then, select the Self-managed secrets tab. The UI is organized as follows: The filter panel on the left lists each secret type and its count, including generic secret, AK/SK secret, database secret, and ECS secret. The list on the right shows the secret name, secret type, creator, creation date, tags, description, and actions (Details, Schedule deletion, Cancel deletion).

  2. 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, we recommend that you use CloudMonitor, Simple Log Service (SLS), and ActionTrail to comprehensively monitor the shared and dedicated gateways before, during, and after the migration. The following sections describe key observation points and recommended actions.

  1. Before migration: Observe the shared gateway dashboard

    Until you complete the migration and switch the client endpoint, all KMS requests continue to be processed by the shared gateway. At this stage, focus on the stability and performance of the shared gateway.

    • 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 Product Monitoring section, search for Key Management Service to view the Shared gateway dashboard.

    Note

    We recommend that you record baseline metrics before the migration to use as a reference for comparison.

  2. 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

      Method

      Dedicated gateway

      • Error codes

      • Changes in request latency

      • QPS trends match expectations

      CloudMonitor: KMS dedicated gateway dashboard

      Shared gateway

      • Verify that traffic has fully transitioned.

      • Identify any remaining or abnormal requests.

      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 switched endpoints. You must investigate the issue.

  3. Log-level observation: Analyze detailed access logs by using SLS

    To achieve more granular request tracking and problem diagnosis, we recommend that you 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 ID, 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.

  4. 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
Previous：Step 1: Pre-migration assessmentNext：Update Terraform configurations after migration