Set up automatic rotation using the AWS CLI - AWS Secrets Manager
Prerequisite for database secrets: Choose a rotation strategyStep 1: Write the rotation function codeStep 2: Create the Lambda functionStep 3: Set up network accessStep 4: Configure the secret for rotationNext steps

Set up automatic rotation using the AWS CLI

This tutorial describes how to set up Rotation by Lambda function by using the AWS CLI. When you rotate a secret, you update the credentials in both the secret and the database or service that the secret is for.

You can also set up rotation using the console. For database secrets, see Automatic rotation for database secrets (console). For all other types of secrets, see Automatic rotation for non-database secrets (console).

To set up rotation using the AWS CLI, if you are rotating a database secret, you first need to choose a rotation strategy. If you choose the alternating users strategy, you must store a separate secret with credentials for a database superuser. Next, you write the rotation function code. Secrets Manager provides templates you can base your function on. Then you create a Lambda function with your code and set permissions for both the Lambda function and the Lambda execution role. The next step is to make sure that the Lambda function can access both Secrets Manager and your database or service through the network. Finally, you configure the secret for rotation.

Prerequisite for database secrets: Choose a rotation strategy

For information about the strategies offered by Secrets Manager, see Lambda function rotation strategies.

Option 1: Single user strategy

If you choose the single user strategy, you can continue with Step 1.

Option 2: Alternating users strategy

If you choose the alternating users strategy, you must:

  • Create a secret and store database superuser credentials in it. You need a secret with superuser credentials because alternating users rotation clones the first user, and most users do not have that permission.

  • Add the ARN of the superuser secret to the original secret. For more information, see JSON structure of AWS Secrets Manager secrets .

Note that Amazon RDS Proxy does not support the alternating users strategy.

Step 1: Write the rotation function code

To rotate a secret, you need a rotation function. A rotation function is a Lambda function that Secrets Manager calls to rotate your secret. For more information, see Rotation by Lambda function. In this step, you write the code that updates the secret and the service or database that the secret is for.

Secrets Manager provides templates for Amazon RDS, Amazon Aurora, Amazon Redshift, and Amazon DocumentDB database secrets in Rotation function templates.

To write the rotation function code

  1. Do one of the following:

  2. Save the file in a ZIP file my-function.zip along with any required dependencies.

Step 2: Create the Lambda function

In this step, you create the Lambda function using the ZIP file you created in Step 1. You also set the Lambda execution role, which is the role that Lambda assumes when the function is invoked.

To create a Lambda rotation function and execution role

  1. Create a trust policy for the Lambda execution role and save it as a JSON file. For examples and more information, see Lambda rotation function execution role permissions for AWS Secrets Manager. The policy must:

    • Allow the role to call Secrets Manager operations on the secret.

    • Allow the role to call the service that the secret is for, for example, to create a new password.

  2. Create the Lambda execution role and apply the trust policy you created in the previous step by calling iam create-role.

    aws iam create-role \
    --role-name rotation-lambda-role \
    --assume-role-policy-document file://trust-policy.json

  3. Create the Lambda function from the ZIP file by calling lambda create-function.

    aws lambda create-function \
  --function-name my-rotation-function \
  --runtime python3.7 \
  --zip-file fileb://my-function.zip \
  --handler .handler \
  --role arn:aws:iam::123456789012:role/service-role/rotation-lambda-role

  4. Set a resource policy on the Lambda function to allow Secrets Manager to invoke it by calling lambda add-permission.

    aws lambda add-permission \
  --function-name my-rotation-function \
  --action lambda:InvokeFunction \
  --statement-id SecretsManager \
  --principal secretsmanager.amazonaws.com \
  --source-account 123456789012

Step 3: Set up network access

For more information, see Network access for Lambda rotation function.

Step 4: Configure the secret for rotation

To turn on automatic rotation for your secret, call rotate-secret. You can set a rotation schedule with a cron() or rate() schedule expression, and you can set a rotation window duration. For more information, see Rotation schedules.

aws secretsmanager rotate-secret \
    --secret-id MySecret \
    --rotation-lambda-arn arn:aws:lambda:Region:123456789012:function:my-rotation-function \
    --rotation-rules "{\"ScheduleExpression\": \"cron(0 16 1,15 * ? *)\", \"Duration\": \"2h\"}"

Next steps

See Troubleshoot AWS Secrets Manager rotation.