You can manage the account of an ApsaraDB RDS database in an ApsaraDB RDS secret of Key Management Service (KMS). In this case, if you integrate Alibaba Cloud SDK, KMS Instance SDK, or a secret SDK into your application, your application can dynamically retrieve the secret from KMS to log on to the ApsaraDB RDS database. You can configure secret rotation to reduce the risks of account leaks. This topic describes how to manage and use ApsaraDB RDS secrets.
Feature description
If you use ApsaraDB RDS secrets, you do not need to configure static database accounts in applications. After you create an ApsaraDB RDS secret for an account of an ApsaraDB RDS database in KMS, applications can call the GetSecretValue operation to retrieve the secret to access the database.
If you manage ApsaraDB RDS accounts in KMS, do not modify or delete the accounts in ApsaraDB RDS. Otherwise, service failures may occur.
Rotate an ApsaraDB RDS secret
When KMS rotates an ApsaraDB RDS secret, the password of the associated ApsaraDB RDS account is changed. The username of the account remains unchanged. In most cases, the rotation of an ApsaraDB RDS secret is immediately complete. If the rotation is not complete after more than 2 minutes, check whether the associated ApsaraDB RDS instance and the associated ApsaraDB RDS account are normal.
When an ApsaraDB RDS secret is being rotated, do not delete the ApsaraDB RDS instance and ApsaraDB RDS account that are associated with the ApsaraDB RDS secret. Otherwise, rotation failure occurs.
When you use KMS to manage ApsaraDB RDS secrets, you can use the single-account mode and the dual-account mode to manage the secrets. The rotation policies are different.
Single-account mode
Rotation involves generating a new password for the account in a secret. When the password is switched, the current version of the secret may be temporarily unavailable. We recommend that you configure retry policies.
Dual-account mode
During the second rotation, the password of the first account is changed. KMS alternately changes the passwords of the two accounts each time the secret is rotated. The following figure shows the details.
Usage notes
KMS supports the following types of ApsaraDB RDS instances: ApsaraDB RDS for MySQL, ApsaraDB RDS for MariaDB, ApsaraDB RDS for SQL Server, and ApsaraDB RDS for PostgreSQL. KMS does not support ApsaraDB RDS for SQL Server instances that run SQL Server 2017 EE.
Do not create multiple ApsaraDB RDS secrets for a single account of an ApsaraDB RDS database. If you create multiple ApsaraDB RDS secrets for a single account and one of the ApsaraDB RDS secrets is rotated, the password stored in the ApsaraDB RDS secret changes. In this case, you cannot use the secret values of other ApsaraDB RDS secrets to log on to the ApsaraDB RDS database.
Prerequisites
A KMS instance is created and enabled. For more information, see Purchase and enable a KMS instance.
A symmetric key for encrypting secrets is created in a KMS instance. For more information, see Create a key.
An ApsaraDB RDS instance is created. For more information, see Step 1: Create an ApsaraDB RDS for MySQL instance and configure databases.
If you use a Resource Access Management (RAM) user or a RAM role to manage ApsaraDB RDS secrets, the AliyunKMSSecretAdminAccess system policy is attached to the RAM user or the RAM role. For more information, 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 for the secret. This helps reduce the risk of secret leaks.
Log on to the KMS console. In the top navigation bar, select a region. In the left-side navigation pane, choose .
Click the Database Secrets tab, select the ID of the KMS instance from the Instance ID drop-down list, choose . In the panel that appears, configure the parameters and click OK.
NoteYou cannot create multiple ApsaraDB RDS secrets at a time.
When you create an ApsaraDB RDS secret, the system automatically creates the AliyunServiceRoleForKMSSecretsManagerForRDS service-linked role and attaches the AliyunServiceRolePolicyForKMSSecretsManagerForRDS policy to the role. KMS assumes the role to manage ApsaraDB RDS secrets. For example, KMS can rotate the passwords of ApsaraDB RDS accounts.
You can log on to the RAM console to view the details of service-linked roles and policies. For more information, see View the information about a RAM role and View the basic information about a policy.
Parameter
Description
Database Type
The type of database secret that you want to create. Select ApsaraDB RDS Secrets.
Secret Name
The name of the secret. The secret name is unique within the current region.
ApsaraDB RDS Instance
The existing ApsaraDB RDS instance that you want to manage within your Alibaba Cloud account.
Account Management
Manage Dual Accounts (recommended): This mode is suitable for the scenarios in which the secret is used by applications to access the ApsaraDB RDS instance. In this mode, KMS manages two accounts that have identical permissions. This mode ensures that the connections between applications and the ApsaraDB RDS instance are not interrupted when the secret is rotated.
Click the Create Account tab, specify a username prefix, select a database, and then specify permissions.
NoteKMS does not immediately create accounts. KMS creates accounts after you review and confirm the secret information.
Click the Import Existing Accounts tab, select usernames, and then specify passwords for the usernames.
NoteWe recommend that you specify the same passwords as the passwords that you specified for the accounts when you created the ApsaraDB RDS instance. If a username and the specified password do not match, you can retrieve the valid username and password the first time the secret is rotated.
Manage Single Account: This mode is suitable for the scenarios in which a privileged account or a manual O&M account is managed. In this mode, the current version of the secret may be temporarily unavailable when the secret is rotated.
Click the Create Account tab, specify a username prefix, and then select an account type.
You can select Standard Account or Privileged Account for the Account Type parameter. If you select Standard Account, you must select a database and specify the permissions of the account.
Click the Import Existing Accounts tab, select a username, and then specify a password for the username.
CMK
The key that is used to encrypt the current value of the secret.
ImportantYour key and secret must belong to the same KMS instance. The key must be a symmetric key. For more information about the symmetric keys supported by KMS, see Key types and specifications.
If you are a RAM user or a RAM role, you must have the permissions to call the GenerateDataKey operation by using a key.
Tag
The tag that you want to add to the secret. You can use tags to classify and manage secrets. A tag consists of a key-value pair.
NoteA tag key or a tag value can be up to 128 characters in length and can contain letters, digits, forward slashes (/), backslashes (\), underscores (_), hyphens (-), periods (.), plus signs (+), equal sign (=), colons (:), at signs (@), and spaces.
A tag key cannot start with aliyun or acs:.
You can configure up to 20 key-value pairs for each secret.
Automatic Rotation
Specifies whether to enable automatic secret rotation.
Rotation Period
The interval of automatic secret rotation. This setting is required only when you enable automatic rotation. The value ranges from 6 hours to 365 days.
KMS periodically updates the secret based on the value of this parameter.
Description
The description of the secret.
Policy Settings
The policy settings of the secret. For more information, see Overview.
You can use the default policy and then modify the policy based on your business requirements after you create the secret.
Step 2: Integrate an ApsaraDB RDS secret into an application
KMS provides Alibaba Cloud SDK, KMS Instance SDK, the secret client, and the secret JDBC client to retrieve secrets. Your application can use the SDKs to integrate ApsaraDB RDS secrets. The secret JDBC client encapsulates business logic, best practices, and design patterns. Your application can use an ApsaraDB RDS secret that is managed in KMS to implement identity authentication to access the associated database by using JDBC API. For more information about SDKs, see SDK references.
If your application is developed in Java, we recommend that you use the secret JDBC client. For more information, see Secret JDBC client. If your application is developed in Python or Go, we recommend that you use the secret client. For more information, see Secret client. If your application is developed in other programming languages, we recommend that you use KMS Instance SDKs or Alibaba Cloud SDK.
If you want to use SDKs to perform management operations, such as creating ApsaraDB RDS secrets and modifying tags of ApsaraDB RDS secrets, you can use only Alibaba Cloud SDK.
What to do next
Rotate an ApsaraDB RDS secret
When an ApsaraDB RDS secret is being rotated, KMS sends a request to ApsaraDB RDS to change the password of the associated ApsaraDB RDS account. Before you rotate an ApsaraDB RDS secret, make sure that all your applications retrieve the ApsaraDB RDS secret from KMS. This helps prevent application unavailability.
If you delete the instance or account in ApsaraDB RDS that is associated with an ApsaraDB RDS secret, KMS cannot rotate the secret. We recommend that you perform an account check before the rotation and perform the rotation after KMS prompts that the check is successful.
You can configure automatic rotation for a secret to reduce the risk of secret leaks. If a secret is leaked, you can immediately rotate the secret in the KMS console to eliminate intrusion risks.
Log on to the KMS console. In the top navigation bar, select a region. In the left-side navigation pane, choose .
Click the Database Secrets tab, select the ID of the KMS instance from the Instance ID drop-down list, find the secret that you want to rotate, and then click Details in the Actions column.
In the Versions tab, click Configure Rotation. After the check is complete, view the check result.
Automatic Rotation: If you turn on Automatic Rotation, you must select a rotation period. The value ranges from 6 hours to 365 days.
Rotation Now: If you select this option, KMS immediately rotates the secret.
Perform an account check
KMS checks whether an account that is protected by a secret belongs to the associated ApsaraDB RDS instance. If yes, the secret can be rotated. If no, you must delete the secret and create another ApsaraDB RDS secret.
Log on to the KMS console. In the top navigation bar, select a region. In the left-side navigation pane, choose .
Click the Database Secrets tab, select the ID of the KMS instance from the Instance ID drop-down list, find the secret that you want to manage, and then click Details in the Actions column.
In the Versions tab, click Check Account. After the check is complete, view the check result.
Delete an ApsaraDB RDS secret
Before you delete an ApsaraDB RDS secret, make sure that the ApsaraDB RDS secret is no longer in use. If you delete an ApsaraDB RDS secret that is in use, service failures may occur.
You can immediately delete an ApsaraDB RDS secret or create a scheduled task to delete an ApsaraDB RDS secret. If you delete an ApsaraDB RDS secret, the ApsaraDB RDS secret is deleted only from KMS. The username and password of the secret are not deleted in ApsaraDB RDS.
Log on to the KMS console. In the top navigation bar, select a region. In the left-side navigation pane, choose .
Click the Database Secrets tab, select the ID of the KMS instance from the Instance ID drop-down list, find the secret that you want to delete, and then click Schedule Deletion in the Actions column.
In the Schedule Deletion dialog box, select a method to delete the secret and click OK.
If you select Schedule Deletion, configure Retention Period (7 to 30 Days). When the scheduled deletion period ends, KMS deletes the secret.
If you select Delete Immediately, the system immediately deletes the secret.
During the scheduled deletion period, you can click OK in the Actions column to cancel the deletion.
Add tags to secrets
You can use tags to classify and manage secrets. A tag consists of a key-value pair.
A tag key or a tag value can be up to 128 characters in length and can contain letters, digits, forward slashes (/), backslashes (\), underscores (_), hyphens (-), periods (.), plus signs (+), equal sign (=), colons (:), at signs (@), and spaces.
A tag key cannot start with aliyun or acs:.
You can configure up to 20 key-value pairs for each secret.
Add tags for a secret
Solution | Description |
Method 1: Add tags on the Secrets page |
|
Method 2: Add tags on the Secret Details page |
|
icon in the Tag column. 
icon next to Tag. Configure tags for multiple secrets at a time
Log on to the KMS console. In the top navigation bar, select a region. In the left-side navigation pane, choose .
Click a tab based on the type of your secret, select the required instance ID from the Instance ID drop-down list, and then select the desired secrets from the secret list.
Add tags: In the lower part of the secret list, click Add Tag. In the Add Tag dialog box, enter multiple Tag Key and Tag Value, and click OK. In the message that appears, click Close.
Remove tags: In the lower part of the secret list, click Remove Tag. In the Batch Remove dialog box, select the tags that you want to remove and click Remove. In the message that appears, click Close.