When your applications are deployed across multiple regions for primary-standby or active-active disaster recovery, use cross-region synchronization to replicate keys and secrets from a primary KMS instance to replica instances in other regions. This ensures cryptographic resource consistency so applications in each region can perform encryption and decryption locally. This topic describes how to synchronize resources across KMS instances.
How it works
KMS instances support cross-region resource synchronization, completing synchronization within minutes. After cross-region synchronization is configured, business applications that use KMS keys for encryption can achieve geo-redundancy: applications in the primary region access the primary KMS instance for cryptographic operations, while in a disaster recovery scenario, applications in the replica region access the local replica instance.
KMS synchronizes resources between the primary instance and replica instances only. This does not include synchronization of your application-level business data, which must be handled separately.
Scope
Primary instance requirements:
The instance must be owned by the currently logged-in account and must not have been synchronized to any replica instance.
The instance must be a software key management instance with the subscription billing method.
Replica instance restrictions:
Quantity: Each primary instance can be associated with up to three replica instances.
Region: The primary instance and all replica instances must reside in different regions.
Resources: The replica instance must not have any keys or secrets created. You cannot associate an instance that already contains resources.
Quota: The key quota and secret quota of the replica instance must be greater than or equal to those of the primary instance.
Billing: The replica instance must use the subscription billing method.
Version: To synchronize secrets, both the primary and replica instances must be version 3.11.0 or later.
Cross-border restriction: Cross-border synchronization is not supported. The primary instance and all replica instances must reside within the same geographic boundary. For example, when the primary instance resides in a region within the Chinese mainland, all replica instances must also reside in regions within the Chinese mainland.
Resource synchronization details
Synchronization scope
Both keys and secrets are supported for synchronization.
Keys: The key ID, key versions, key material, key status, and deletion protection are synchronized. Key policies, key aliases, and key tags are not synchronized.
NoteExternal key material (BYOK) is not currently supported for synchronization.
Secrets: General secrets, RAM credentials, database credentials, and managed ECS credentials are synchronized.
NoteSecret synchronization requires both the primary and replica instances to be version 3.11.0 or later.
Rotation logic
When automatic rotation is enabled for a key that has cross-region synchronization configured, KMS performs the following steps to ensure encrypted data remains decryptable:
Synchronize the newly created key version to all replica instances first.
Promote the new version to the primary key version on both the primary instance and all replica instances simultaneously.
Key policy synchronization
No automatic sync: Key policies are not automatically synchronized with the key to replica instances. If a custom policy is configured on the primary instance key, applications accessing the replica instance through Alibaba Cloud SDK may fail due to insufficient permissions.
Recommendation: When applications use Alibaba Cloud SDK to perform cryptographic operations, review the key policies on the primary instance and manually configure identical policies on each replica instance. This ensures applications retain access to the replicated keys. For more information, see Key Policy Overview and Custom Key Policies.
Synchronization frequency
After a replica instance is associated, an initial synchronization runs immediately and takes approximately 3 to 5 minutes. Subsequently, synchronization runs every minute.
Conflict handling
If a key with the same ID already exists on the replica instance, the system skips that key and continues synchronizing the remaining resources.
Procedure
Purchase and enable a replica instance. For more information, see Purchase a KMS instance.
Log on to the Key Management Service console. In the top navigation bar, select a region. In the left-side navigation pane, choose .
In the left-side navigation pane, choose Cross-region Synchronization, and then click Add Replica Instance.
On the Configure Replica Instance page, select the primary instance and the replica instance, and then click Next.
NoteSynchronization Policy supports only
ignore, which skips duplicate resources when the same key ID or secret name is encountered and continues synchronizing the remaining resources.On the Synchronize Resources page, select the synchronization types for keys and secrets, and then click Next.
Key Sync Type: Multiple selection is supported. However, you cannot select both Full Synchronization and Synchronization of Selected Resources at the same time.
Synchronization type
Description
Full Synchronization
Synchronizes only the keys that currently exist in the primary instance. Keys created afterward are not synchronized. Changes to synchronized keys are automatically synced.
Incremental Key Synchronization
Existing keys in the primary instance are not synchronized. Only keys created afterward are synchronized.
Synchronization of Selected Resources
Only the keys you select are synchronized. Changes to these keys are automatically synced. In the expanded key resource panel, select the keys to synchronize from the left side.
Secret Sync Type: Multiple selection is supported. However, you cannot select both Full Synchronization and Synchronization of Selected Resources at the same time.
ImportantSecret synchronization requires both the primary and replica instances to be version 3.11.0 or later. If the version check fails, the secret synchronization task cannot be created. Upgrade the instance version first.
Synchronization type
Description
Full Synchronization
Synchronizes all secrets that currently exist in the primary instance. Secrets created afterward are not synchronized.
Incremental Secret Sync
Existing secrets in the primary instance are not synchronized. Only secrets created afterward are synchronized.
Synchronization of Selected Resources
Only the secrets you select are synchronized. Changes to these secrets are automatically synced. In the expanded secret resource panel, select the secrets to synchronize from the left side.
Confirm the configurations and click Done. Synchronization takes approximately 3 to 5 minutes.
On the synchronization results page, view the synchronization results and any failure reasons in the Result tab of the target replica instance.
Click Close to return to the Cross-region Synchronization task list. Check the synchronization progress in the Synchronization Task column of the target primary instance.
NoteThe system automatically synchronizes progress every minute. Synchronization progress = (Number of synchronized keys + Number of synchronized secrets) / (Number of keys to synchronize + Number of secrets to synchronize) × 100%.
What to do next
After creating access credentials, applications in the primary and replica regions can use the keys from their respective KMS instances for cryptographic operations. For more information, see Create access credentials.
Alibaba Cloud SDK: Create only one access credential. Only RAM roles whose trusted entity is an Alibaba Cloud service are supported.
KMS Instance SDK (not recommended): Create separate access credentials for the primary instance and each replica instance. Only ClientKeys from application access points (AAPs) are supported. For more information, see Use the KMS Instance SDK.