Rotate generic secrets - Key Management Service - Alibaba Cloud Documentation Center

Generic secrets in Secrets Manager don't rotate automatically. To rotate a generic secret, you push a new secret version using the API. The rotation path you choose depends on whether your system can generate the new credential itself, or whether an external step is required first.

How it works

Two roles interact with Secrets Manager during rotation:

Role	Description
Secret producer	The operations and maintenance (O&M) system or administrator that generates new credentials and writes them to Secrets Manager using CreateSecret and PutSecretValue.
Secret consumer	The application that retrieves credentials by calling GetSecretValue with the secret name. Secrets Manager always returns the version marked ACSCurrent.

Prerequisites

Before you begin, make sure you have:

An initial secret version stored in Secrets Manager and marked ACSCurrent
An application configured to call GetSecretValue by secret name to retrieve credentials at runtime

Choose a rotation path

	Single-call rotation	Multi-call rotation
When to use	Your system generates the new credential automatically—for example, an OAuth 2.0 app secret	Your system cannot generate the credential; a person or external system must create it first—for example, an ApsaraDB RDS account or an Elastic Compute Service (ECS) SSH key
API calls required	1 (`PutSecretValue`)	4, with a validation window between steps
Downtime risk	Near-zero: the new value becomes current immediately	None: the old credential stays active until you promote the new version

Rotate using a single API call

Use this path when your system self-generates secrets—for example, an OAuth 2.0 system that creates application secrets automatically.

Generate a new application secret in the OAuth 2.0 system.
Store the new secret in Secrets Manager. This call marks the new version ACSCurrent and demotes the previous version to ACSPrevious.
```
aliyun kms PutSecretValue \
  --SecretName MyOAuthAppSecret \
  --SecretData sample-app-secret \
  --VersionId v2
```
Verify that the application gets the updated value. Call GetSecretValue and confirm it returns the new secret.

Rotate using multiple API calls

Use this path when you need to create a new credential in an external system and validate it before making it current—for example, when rotating a database account password.

Staging the new credential under a custom label (for example, MyPendingLabel) before promoting it to ACSCurrent provides a validation window. If anything fails mid-rotation, the old ACSCurrent version remains intact and your application keeps running.

The following example rotates the username and password for a database managed in Secrets Manager.

Step 1: Generate a random password

Call GetRandomPassword to generate a new password.

aliyun kms GetRandomPassword --ExcludePunctuation true

Secrets Manager returns a RandomPassword value:

{
    "RequestId": "e36ca295-6e47-4dfb-9df1-48d19df41545",
    "RandomPassword": "v2GwsgcuNylyYw9JGJNE5yBViGSi****"
}

Step 2: Store the new credential under a pending label

Store the new username and password as a new secret version marked MyPendingLabel. The existing ACSCurrent and ACSPrevious versions remain unchanged, so your application continues to work during this step.

aliyun kms PutSecretValue \
    --SecretName db_cred \
    --SecretData "{\"uname\": \"alice\", \"pwd\": \"v2GwsgcuNylyYw9JGJNE5yBViGSiZ****\"}" \
    --VersionId v2 \
    --VersionStages "[\"MyPendingLabel\"]"

Step 3: Register the new credential with the database

Create the new database account using the v2 version credentials. At this point, only the v2 version of db_cred can authenticate with the database. Do not promote the version to ACSCurrent until this step succeeds.

Step 4: Promote the new version to current

After the new credential is registered and validated, update the version stage to make v2 the active version.

aliyun kms UpdateSecretVersionStage \
    --SecretName db_cred \
    --VersionStage ACSCurrent \
    --MoveToVersion v2

Step 5: Verify the rotation

Call GetSecretValue and confirm that Secrets Manager returns the v2 credentials (username alice and the new password).

What's next

For databases managed by ApsaraDB RDS, use a dynamic secret to let Secrets Manager handle rotation automatically. See Overview of Dynamic ApsaraDB RDS secrets.