Rotate database secrets with Secrets Manager

For an RDS or Aurora master password, let RDS manage it (--manage-master-user-password): no Lambda function, and rotation every 7 days by default. For application users, or anything RDS doesn't manage, use a Lambda rotation function. Either way, clients must re-read the secret when a login fails, rather than caching it forever.

Option A: RDS-managed master password

aws rds modify-db-instance --db-instance-identifier mydb \
  --manage-master-user-password \
  --master-user-secret-kms-key-id alias/my-key \
  --apply-immediately

• Omit --master-user-secret-kms-key-id to use Secrets Manager's default key. A key in another account must be named by ARN. The key can't be changed later.
• describe-db-instances shows MasterUserSecret with SecretArn, SecretStatus (creating, active, rotating or impaired) and KmsKeyId. The example secret ARNs contain rds!.
• Rotation is every 7 days by default. The schedule can be modified, and --rotate-master-user-password together with --apply-immediately rotates now. Generated passwords are 28 characters.
• Not supported with:
• creating read replicas from such a source (except RDS for SQL Server and Db2);
• Blue/Green Deployments;
• RDS Custom;
• Oracle Data Guard switchover.

Plan around these before you switch.

Option B: a Lambda rotation function

Schedule (SDK RotationRules):

• ScheduleExpression (rate(…) or cron(…), UTC; as often as every four hours), or AutomaticallyAfterDays, not both. Hour-based schedules need ScheduleExpression.
• Duration sets the window, for example 3h, and must not reach into the next window. Without it, hourly schedules close after one hour and daily ones at the end of the day. The window starts at midnight unless you set a start time.
• Failed rotations are retried several times.
• Turning rotation on in the console needs iam:CreateRole and iam:AttachRolePolicy, because it creates the function's role.

import { SecretsManagerClient, RotateSecretCommand } from "@aws-sdk/client-secrets-manager";

const sm = new SecretsManagerClient({});
await sm.send(new RotateSecretCommand({
  SecretId: "prod/app/db",
  RotationLambdaARN: "arn:aws:lambda:<region>:<account-id>:function:<rotation-fn>",
  RotationRules: { ScheduleExpression: "rate(30 days)", Duration: "3h" },
}));

What a rotation does

1. createSecret: stores a new version labelled AWSPENDING. The version ID is the request token, so retries reuse it.
2. setSecret: changes the password in the database to the pending value. It first checks that AWSCURRENT works and refers to the same user and host.
3. testSecret: logs in with the pending value.
4. finishSecret: moves AWSCURRENT to the new version. The old one becomes AWSPREVIOUS.

If AWSPENDING sits on a version other than AWSCURRENT, later rotations assume a rotation is still running and fail. A failed run can leave AWSPENDING on an empty version. The fix is to clear AWSPENDING and retry.

Network

The function runs in the database's VPC and security group, and it must also reach the Secrets Manager endpoint: through an interface VPC endpoint (preferred) or NAT. For alternating users with an RDS-managed superuser secret, it also needs the RDS API endpoint. The endpoint's security group must admit the VPC's CIDR on 443, and its endpoint policy must allow the function (patterns/iam-to-vpc-endpoints.md).

Make clients survive rotation

• Read the secret by name. The default GetSecretValue returns AWSCURRENT.
• Cache it, but on an authentication failure re-read it once and reconnect before failing (guides/rds/connect-securely.md).

When rotation fails (CloudWatch logs of the rotation function)