Key Management Service:Migrate secrets across regions

Step 1: Query and save the secret details in the source region

Call the following APIs in the source region to retrieve all the information you need to re-create the secret:

For example, if ListSecretVersionIds returns three versions, sort them by creation time:

Step 2: Migrate your application to the destination region

1. Move your application to the destination region.

2. Create a credential for the application in the destination region:

   • If using an AccessKey pair of a Resource Access Management (RAM) user or RAM role: Create a RAM user or RAM role in the destination region and attach the AliyunKMSSecretAdminAccess policy. See Create a RAM user and grant permissions to the RAM user and Create a RAM role and attach the required policies to the role.

   • If using a client key of an application access point (AAP): Purchase a KMS instance first, then create a client key in the destination region. See Create an AAP.

3. Update the endpoint and credential settings in your application.

   KMS endpoints and KMS instance endpoints are different. Configure the endpoint based on the SDK you use. For details, see SDK references.

Step 3: Create the secret in the destination region

1. Purchase a KMS instance in the destination region. See Instance selection and Purchase and enable a KMS instance.

2. Create a key in the KMS instance to encrypt the secret. See Getting started with Key Management.

3. Call the following APIs to re-create the secret with identical metadata, versions, and values:

   API	What to set
   CreateSecret	Use the values from DescribeSecret for secretName, secretType, Tags, Description, and ExtendedConfig. For VersionId, use the initial version (v1 in this example). For SecretData and SecretDataType, use the values from GetSecretValue for the initial version.
   PutSecretValue	Store each remaining version. In this example, call once for v2 and once for v3.
   UpdateSecretVersionStage	Set the stage for each version. In this example: v1 → 001, v2 → ACSPrevious, v3 → ACSCurrent.

4. Call DescribeSecret in both regions and confirm that the information about the secret is the same.

Step 4: Verify your application

Test your application in the destination region to confirm it can access the secret and runs as expected.

Step 5: Delete the secret in the source region

After confirming the application works correctly in the destination region, delete the secret in the source region. See Manage and use generic secrets.

Use ActionTrail to check recent API calls to a secret before deleting it. Secret-related events include GetSecretValue, DescribeSecret, ListSecretVersionIds, PutSecretValue, UpdateSecret, UpdateSecretVersionStage, UpdateSecretRotationPolicy, and RestoreSecret. See Use ActionTrail to query KMS events and Audit events of KMS.