Store ApsaraDB RDS database credentials in Key Management Service (KMS) so applications can retrieve them dynamically — no hardcoded passwords, no manual rotation.
How it works
When you create an ApsaraDB RDS secret in KMS, KMS stores the database account's username and password as a versioned secret. Applications call the GetSecretValue operation to retrieve the current credentials at runtime.
After storing an ApsaraDB RDS account's credentials in KMS, do not modify or delete the account in ApsaraDB RDS. Doing so breaks the secret and causes service disruptions.
Rotation strategies
KMS changes the account password when rotating a secret — the username stays the same. Rotation typically completes instantly. If rotation takes longer than 2 minutes, verify that the associated ApsaraDB RDS instance and account are functioning properly.
Do not delete the ApsaraDB RDS instance or account associated with the secret during rotation, as this causes rotation to fail.
KMS supports two rotation strategies. Choose based on your availability requirements:
| Strategy | How it works | Use when |
|---|---|---|
| Dual-account (recommended) | KMS manages two accounts with identical permissions and alternates between them during rotation. One account always has valid credentials while the other is being updated. | Applications need uninterrupted database access during rotation |
| Single-account | KMS updates the password of a single account. The current version of the secret may be briefly unavailable during the password switch. | Managing a privileged account or a manual O&M account where brief downtime is acceptable |
Single-account rotation: Set up a retry policy in your application to handle the brief period when credentials may be unavailable.
Dual-account rotation: On the first rotation, KMS creates a second account. On subsequent rotations, KMS alternates password changes between the two accounts.
Limitations
Supported databases: ApsaraDB RDS for MySQL, ApsaraDB RDS for MariaDB, ApsaraDB RDS for SQL Server (except SQL Server 2017 Cluster Edition), and ApsaraDB RDS for PostgreSQL.
Do not store the same ApsaraDB RDS account credentials in multiple secrets. Rotating one secret updates the password, making the other secrets' values invalid for database login.
Prerequisites
Before you begin, make sure you have:
A KMS instance that is created and enabled. See Purchase and enable a KMS instance.
A symmetric key for encrypting secrets, created in the KMS instance. See Manage keys.
An ApsaraDB RDS instance. See Create an ApsaraDB RDS for MySQL instance.
(For RAM users and RAM roles) The AliyunKMSSecretAdminAccess system policy granted by the Alibaba Cloud account. See Grant permissions to a RAM user or Grant permissions to a RAM role.
Step 1: Create an ApsaraDB RDS secret
When you create a secret, you can configure automatic rotation to reduce the risk of credential exposure.
Log on to the KMS console. In the top navigation bar, select a region. In the left navigation pane, choose Resource > Secrets.KMS consoleKMS console
Click the Database Secrets tab, select an Instance ID, and then click Create Secret > Create Single Secret.
Configure the secret parameters, then click Confirm.
You cannot create multiple ApsaraDB RDS secrets at once.
When you create an ApsaraDB RDS secret, KMS automatically creates the service-linked role AliyunServiceRoleForKMSSecretsManagerForRDS with the permission policy AliyunServiceRolePolicyForKMSSecretsManagerForRDS. KMS assumes this role to manage ApsaraDB RDS secrets, including rotating passwords. To view the role and policy details, see View the information about a RAM role and View the information about a policy.
Parameter reference:
| Parameter | Description |
|---|---|
| Database type | The type of database secret. Select ApsaraDB RDS Secrets. |
| Secret name | A unique name for the secret within the current region. |
| ApsaraDB RDS instance | The ApsaraDB RDS instance to associate with the secret. |
| Account management | The rotation strategy. Manage Dual Accounts (recommended) manages two accounts with identical permissions for zero-downtime rotation. Manage Single Account manages a single account, which may have brief downtime during rotation. Dual-account – Create Account tab: Specify a username prefix, select a database, and specify permissions. KMS creates the accounts after you confirm the secret. Dual-account – Import Existing Accounts tab: Select usernames and specify their passwords. Use the same passwords as when the accounts were created in the RDS instance. If a password doesn't match, KMS retrieves the valid credentials on the first rotation. Single-account – Create Account tab: Specify a username prefix and select an account type (Standard account or Privileged account). For standard accounts, select a database and specify permissions. Single-account – Import Existing Accounts tab: Select a username and specify its password. |
| CMK | The symmetric key used to encrypt the secret. The key and the secret must belong to the same KMS instance. If you are a RAM user or RAM role, you must have the GenerateDataKey permission for the key. For supported symmetric key types, see Key specifications for symmetric and asymmetric encryption. |
| Tag | (Optional) Tags for classifying and managing secrets. Each tag is a key-value pair. Tag key and value constraints: up to 128 characters each; allowed characters: letters, digits, /, \, _, -, ., +, =, :, @, spaces. Tag keys cannot start with aliyun or acs:. Up to 20 tags per secret. |
| Automatic rotation | Whether to enable automatic secret rotation. |
| Rotation period | The interval for automatic rotation, from 6 hours to 365 days. Required only when automatic rotation is enabled. |
| Description | (Optional) A description of the secret. |
| Advanced settings > Policy settings | (Optional) Access policy for the secret. See Overview of secret policies. |
Step 2: Integrate the secret into an application
Applications retrieve the ApsaraDB RDS secret by calling the GetSecretValue (OpenAPI) operation. KMS provides several client options depending on your language and deployment model.
Implement a retry mechanism in your application to handle transient errors.
For authentication, use an ECS instance RAM role or a standard RAM role for enhanced security.
Endpoints: shared gateway — see Endpoint; dedicated gateway —
{INSTANCE_ID}.cryptoservice.kms.aliyuncs.com.
Choose a client based on your language and scenario:
| Client | Supported languages | Gateway | Use when |
|---|---|---|---|
| Secret JDBC Client | Java 8+ | Shared or dedicated | You use MySQL, SQL Server, PostgreSQL, or MariaDB and want the client to handle JDBC connection authentication automatically. |
| Secret Client | Java 8+, Go, Python | Shared or dedicated | You want a lightweight client with built-in caching and automatic secret refresh. |
| Alibaba Cloud SDK | Java 8+ (Java 6+ with SDK V1.0), PHP, Go, Python, .NET (C#), C++, TypeScript, Swift | Dedicated (recommended) or shared | You are already using Alibaba Cloud SDK in your application. |
| KMS Agent | Any language (HTTP API) | Dedicated (recommended) or shared | Ideal for multi-application deployments where many applications access KMS. It offers standardized HTTP APIs, supporting applications written in any language. |
| KMS instance SDK (not recommended) | Java 8+, PHP, Go, Python, .NET (C#) | Dedicated only | — |
What's next
Rotate the secret
During rotation, KMS requests ApsaraDB RDS to change the associated account's password. Make sure all applications retrieve the secret from KMS before starting rotation to avoid downtime.
If the ApsaraDB RDS instance or account associated with the secret has been deleted, KMS cannot rotate the secret. Run an account check first and proceed only after KMS confirms the check succeeds.
Configure automatic rotation to reduce long-term exposure risk. For an immediately leaked secret, rotate it manually from the KMS console.
Log on to the KMS console. In the top navigation bar, select a region. In the left navigation pane, choose Resource > Secrets.KMS consoleKMS console
Click the Database Secrets tab, select an Instance ID, locate the secret, and click Actions in the Details column.
In the Versions section at the bottom of the secret details page, click Configure Rotation.
Automatic rotation: Enable and select a rotation period from 6 hours to 365 days.
Rotation now: Select this option to rotate the secret immediately.
Check the secret value
KMS verifies whether the account protected by the secret belongs to the associated ApsaraDB RDS instance. If the check fails, delete the secret and create a new one.
Log on to the KMS console. In the top navigation bar, select a region. In the left navigation pane, choose Resource > Secrets.KMS consoleKMS console
Click the Database Secrets tab, select an Instance ID, locate the secret, and click Actions in the Details column.
In the Versions section, click Check Account and view the result.
Delete the secret
Make sure the secret is no longer in use before deleting it to prevent service failures.
Deleting a secret removes it from KMS only. The associated username and password in ApsaraDB RDS remain intact.
Log on to the KMS console. In the top navigation bar, select a region. In the left navigation pane, choose Resource > Secrets.KMS console
Click the Database Secrets tab, select an Instance ID, locate the secret, and click Actions in the Schedule Deletion column.
In the Schedule Deletion dialog box, select a deletion method and click OK.
Schedule Deletion: Set a retention period from 7 to 30 days. KMS deletes the secret when the period ends. To cancel, click OK in the Actions column before the period ends.
Delete Immediately: KMS deletes the secret right away.
Manage tags
Use tags to classify and manage your secrets. Each tag is a key-value pair.
Tag key and value constraints: up to 128 characters each; allowed characters: letters, digits,
/,\,_,-,.,+,=,:,@, spaces. Tag keys cannot start withaliyunoracs:.Up to 20 tags per secret.
Add tags to a single secret:
| Method | Steps |
|---|---|
| From the Secrets page | 1. Go to Resource > Secrets in the KMS console. 2. Click the appropriate tab, select an Instance ID, find the secret, and click the  icon in the Tag column. 3. Click Add. In the Edit Tag dialog box, enter Tag Key and Tag Value pairs, then click OK. |
| From the Secret details page | 1. Go to Resource > Secrets in the KMS console. 2. Click the appropriate tab, select an Instance ID, find the secret, and click Details in the Actions column. 3. On the Secret details page, click the  icon next to Tag. 4. In the Edit Tag dialog box, enter Tag Key and Tag Value pairs, then click OK. |
Add or remove tags for multiple secrets at once:
Go to Resource > Secrets in the KMS console.
Click the appropriate tab, select an Instance ID, and select the secrets from the list.
At the bottom of the list:
To add tags: Click Add Tag. In the Add Tag dialog box, enter Tag Key and Tag Value pairs, and click OK.
To remove tags: Click Remove Tag. In the Batch Remove dialog box, select the tags to remove and click Cancel. In the message that appears, click Close.