If you use Alibaba Cloud Key Management Service (KMS) 1.0, you can migrate your resources to a KMS 3.0 software key management instance or hardware key management instance in the same region to improve performance and user experience. After the migration, your keys and secrets will be stored in the KMS instance. Keys are unique within a region, and secrets are unique within an Alibaba Cloud account and KMS instance in that region. This topic describes how to migrate resources from KMS 1.0 to a KMS 3.0 instance.
Why migrate
To provide a better product experience, Alibaba Cloud plans to begin the End of Support and Fixes (EOSF) phase for KMS 1.0 starting at 00:00:00 (GMT+8) on March 30, 2025. KMS 1.0 will then enter the End of Support (EOS) phase at 00:00:00 (GMT+8) on September 30, 2025. To prevent business disruptions, migrate your KMS 1.0 resources to a KMS 3.0 instance as soon as possible. Migrating to a KMS 3.0 instance provides the following benefits:
Migration impact
Business impact
The migration affects the following aspects of your business:
Service availability: The KMS migration separates control plane operations from data plane operations. The migration process itself does not affect your business operations. Secret calls, cloud product encryption, and application encryption continue to work as usual.
ImportantDuring the migration time window, control plane operations cannot be performed on keys, secrets, or KMS instances. These operations include creating, modifying, or deleting resources. This restriction prevents migration failures caused by data consistency issues. We recommend performing the migration during off-peak hours.
Terraform compatibility: If you use Terraform to manage KMS, an instance ID property will be added to your resources after the migration. To prevent resources from being released when you perform subsequent control plane operations, you must modify your Terraform configuration after the migration is complete. For more information, see Modify the configuration in a Terraform scenario after migration.
The migration does not affect the following aspects of your business:
SDK compatibility: After migration, custom applications can continue to use the existing software development kit (SDK) without any changes to code or applications. If you use the SDKs of other products, such as Function Compute, for business encryption and decryption, you do not need to modify those SDKs. This ensures an efficient, smooth, and seamless migration.
Performance impact: If you accessed keys and secrets over the public network before migration, you can continue to use the existing SDK after migration. Performance remains unchanged. To improve performance, you can switch from public network access to VPC access. After you switch, the performance will depend on the instance type.
Access control policies: You can continue to use your existing access control policies after migration without any changes.
Other impacts:
After migration, the version IDs of symmetric and asymmetric keys change. If your custom application has validation logic based on key version IDs, you must assess and remove this logic before migration. Otherwise, the change in key version IDs will cause application validation to fail.
NoteIf you use OpenAPI, calls made with the old key version ID will still succeed after migration. You do not need to change your business code.
Cost impact
The billing logic for KMS 3.0 instances is different from KMS 1.0. Before you migrate, you should understand the costs associated with KMS 3.0 instances.For more information, see Subscription billing and Pay-as-you-go.
Notes on key migration
KMS migrates the metadata and key material of customer master keys (CMKs). The metadata includes the key ID, key status, deletion protection, alias, and tags. This data remains unchanged after the migration.
Service keys
Service keys do not need to be migrated. You can continue to use them as usual. You can view service keys in the new console after you log on. Service keys are automatically created by cloud products when you configure server-side encryption. Their aliases are in the format alias/acs/<CloudProduct>.
Customer master keys
Only keys in the Enabling state can be migrated. Keys in other states, such as Disabled or Schedule Deletion, cannot be migrated.
Protection level: Software
The following table shows which instance types you can migrate to.
ImportantBring-Your-Own-Key (BYOK): Migration is supported. KMS directly migrates the key material. You do not need to upload it manually.
Multi-version keys: Migration is supported. KMS migrates all key versions.
If automatic rotation is enabled for a key, you must manually disable it before migration to ensure version consistency. For more information, see Automatic key rotation.
In a hardware key management instance, keys can be stored in a database or an HSM. Keys migrated to a hardware key management instance are stored in the database by default because database-stored keys support rotation. This setting cannot be changed.
Key specification to migrate
Software key management instance
Hardware key management instance
Aliyun_AES_256 (single version)
√
√
Aliyun_AES_256 (multi-version)
√
√
RSA_2048 (single version)
√
×
EC_P256 (single version)
√
×
EC_P256K (single version)
√
×
Protection level: HSM
ImportantOnly keys in the Chinese mainland can be migrated. Keys outside the Chinese mainland cannot be migrated. If you have keys that cannot be migrated, contact us.
BYOK: Migration is not supported.
Multi-version keys: Migration is supported for some key types. KMS migrates all key versions.
If automatic rotation is enabled for a key, you must manually disable it before migration to ensure version consistency. For more information, see Automatic key rotation.
In a hardware key management instance, keys can be stored in a database or an HSM. Keys migrated to a hardware key management instance are stored in the database by default because database-stored keys support rotation. This setting cannot be changed.
The following table shows which instance types you can migrate to.
Key specification to migrate
Software key management instance
Hardware key management instance
Aliyun_AES_256 (single version)
√
√
Aliyun_AES_256 (multi-version)
√
√
Aliyun_SM4 (single version)
×
√
Aliyun_SM4 (multi-version)
×
√
RSA_2048 (single version)
√
√
EC_P256 (single version)
√
√
EC_P256K (single version)
√
√
RSA_3072 (single version)
√
√
EC_SM2 (single version)
×
√
Notes on secret migration
All types of s can be migrated.
In KMS 3.0, secrets must be unique within an Alibaba Cloud account and a KMS instance in a single region. If multiple secrets in KMS 1.0 have the same name, or if a secret with the same name already exists in the destination KMS 3.0 instance, the migration is not supported.
KMS migrates the metadata and all versions of a secret. The metadata includes the secret name, status, and tags. This data remains unchanged after the migration.
Secrets with automatic rotation enabled can be migrated. To ensure version consistency, you must manually disable automatic rotation before migration.
When you migrate a secret, you must also migrate the master key that encrypts it.
Secrets encrypted with a system-managed key can be migrated. However, the data backup feature is not supported for these secrets after migration. For more information about the data backup feature, see Disaster recovery management.
Quickly check for resources to migrate
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.
ImportantData 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.
Choose a suitable KMS 3.0 instance
Evaluate the following aspects to choose a suitable KMS 3.0 instance.
Assess business needs: Choose a suitable KMS instance based on the instance types to which your keys can be migrated.
Assess performance needs: Consider the frequency of data encryption and decryption operations in your business. For example, if your business is a high-traffic E-commerce platform that processes many orders daily, you need to encrypt user payment information (such as bank card numbers and payment passwords) and order data. You may need a KMS instance with a high QPS. In this case, choose a KMS instance that supports 2,000 or 4,000 QPS to ensure that encryption and decryption operations are completed promptly and to avoid transaction delays or failures.
Assess compliance needs: If your business needs to comply with FIPS certification, you must purchase a hardware key management instance.
Assess cost budget: KMS instances offer two billing methods: subscription and pay-as-you-go. The pay-as-you-go method is recommended only if your business uses KMS solely for cloud product encryption. For all other scenarios, we recommend using a subscription instance.