How to use the command "aws-secretsmanager" (with examples)

In this article, we will explore various use cases of the aws secretsmanager command. Secrets Manager is a service provided by AWS that allows you to store, manage, and retrieve secrets securely. We will cover eight different use cases, including listing secrets stored in the current account, creating a secret, deleting a secret, viewing secret details, retrieving the value of a secret, and rotating secrets using a Lambda function.

Use Case 1: List Secrets

To start, let’s look at how to list secrets stored by the Secrets Manager in the current AWS account.

Code

aws secretsmanager list-secrets

Motivation

This example is useful for getting a high-level overview of all the secrets stored in the Secrets Manager. It can help administrators identify and manage the secrets effectively.

Explanation

• list-secrets: This is the command to list all the secrets stored in the current AWS account.

Example Output

{
    "SecretList": [
        {
            "ARN": "arn:aws:secretsmanager:us-east-1:123456789012:secret:my-secret-12345",
            "Name": "my-secret",
            "Description": "My secret description",
            "KmsKeyId": "arn:aws:kms:us-east-1:123456789012:key/my-key-12345",
            "RotationEnabled": false,
            "LastChangedDate": 1630905424.019,
            "SecretVersionsToStages": {
                "EXAMPLE1": ["AWSCURRENT"],
                "EXAMPLE2": ["AWSPENDING"]
            }
        }
    ]
}

The output provides detailed information about each secret, including the ARN, name, description, KMS key ID, rotation status, last changed date, and secret versions with their respective stages.

Use Case 2: Create a Secret

Next, let’s learn how to create a secret in the Secrets Manager.

Code

aws secretsmanager create-secret --name name --description "secret_description" --secret-string secret

Motivation

Creating a secret is essential when you want to securely store sensitive information such as database passwords, API keys, or access tokens. This example demonstrates how to create a secret and specify its name, description, and secret value.

Explanation

• create-secret: This command is used to create a secret in the Secrets Manager.

Arguments

• --name name: The name of the secret. Replace name with the desired name for your secret.
• --description "secret_description": The description of the secret. Replace secret_description with a detailed description of the secret.
• --secret-string secret: The secret value. Replace secret with the actual secret value you want to store.

Example Output

{
    "ARN": "arn:aws:secretsmanager:us-east-1:123456789012:secret:my-secret-12345",
    "Name": "my-secret",
    "VersionId": "EXAMPLE1-90ab-cdef-ghij-klmnopqrstuv",
    "VersionStages": [
        "AWSPREVIOUS",
        "AWSCURRENT"
    ]
}

The output provides information about the created secret, including its ARN, name, version ID, and version stages.

Use Case 3: Delete a Secret

Let’s now explore how to delete a secret from the Secrets Manager.

Code

aws secretsmanager delete-secret --secret-id name_or_arn

Motivation

Deleting a secret is useful when you no longer need to store the secret or want to clean up unused secrets. This example demonstrates how to delete a secret by specifying its name or ARN.

Explanation

• delete-secret: This command is used to delete a secret from the Secrets Manager.

Arguments

• --secret-id name_or_arn: The name or ARN of the secret to be deleted. Replace name_or_arn with the name or ARN of the secret you want to delete.

Example Output

{
    "ARN": "arn:aws:secretsmanager:us-east-1:123456789012:secret:my-secret-12345",
    "Name": "my-secret",
    "DeletionDate": 1630906841.906
}

The output confirms the successful deletion of the secret by providing its ARN, name, and deletion date.

Use Case 4: View Secret Details

Now, let’s see how to view the details of a secret in the Secrets Manager, excluding the secret text.

Code

aws secretsmanager describe-secret --secret-id name_or_arn

Motivation

Viewing secret details allows administrators to get more information about a specific secret. This example demonstrates how to retrieve details such as the ARN, name, description, KMS key ID, rotation status, last changed date, and secret versions.

Explanation

• describe-secret: This command is used to view the details of a secret in the Secrets Manager.

Arguments

• --secret-id name_or_arn: The name or ARN of the secret. Replace name_or_arn with the name or ARN of the secret you want to describe.

Example Output

{
    "ARN": "arn:aws:secretsmanager:us-east-1:123456789012:secret:my-secret-12345",
    "Name": "my-secret",
    "Description": "My secret description",
    "RotationEnabled": false,
    "LastChangedDate": 1630905424.019,
    "SecretVersionsToStages": {
        "EXAMPLE1": ["AWSCURRENT"],
        "EXAMPLE2": []
    }
}

The output provides detailed information about the secret, excluding the actual secret value. This includes the ARN, name, description, rotation status, last changed date, and the secret versions with their respective stages.

Use Case 5: Retrieve Secret Value

Let’s now learn how to retrieve the value of a secret stored in the Secrets Manager.

Code

aws secretsmanager get-secret-value --secret-id name_or_arn --version-stage version_of_secret

Motivation

Retrieving the value of a secret is necessary when you need to fetch the secret value for use in your application or script. This example demonstrates how to retrieve the secret value by specifying the secret’s name or ARN and the version stage.

Explanation

• get-secret-value: This command is used to retrieve the value of a secret from the Secrets Manager.

Arguments

• --secret-id name_or_arn: The name or ARN of the secret. Replace name_or_arn with the name or ARN of the secret you want to retrieve the value from.
• --version-stage version_of_secret: The version stage of the secret. Replace version_of_secret with the version stage of the secret you want to retrieve.

Note: Omitting –version-stage flag will retrieve the latest version of the secret.

Example Output

{
    "ARN": "arn:aws:secretsmanager:us-east-1:123456789012:secret:my-secret-12345",
    "Name": "my-secret",
    "VersionId": "EXAMPLE1-90ab-cdef-ghij-klmnopqrstuv",
    "SecretString": "{\"username\":\"admin\",\"password\":\"supersecret\"}",
    "VersionStages": [
        "AWSPREVIOUS",
        "AWSCURRENT"
    ]
}

The output provides information about the secret, including its ARN, name, version ID, secret string (value), and version stages.

Use Case 6: Rotate Secret Immediately

Next, let’s explore how to manually rotate a secret immediately using a Lambda function.

Code

aws secretsmanager rotate-secret --secret-id name_or_arn --rotation-lambda-arn arn_of_lambda_function

Motivation

Rotating secrets regularly helps enhance security by changing the secret value. This example demonstrates how to manually trigger a secret rotation using a Lambda function, ensuring that the secret is immediately rotated.

Explanation

• rotate-secret: This command is used to rotate a secret in the Secrets Manager.

Arguments

• --secret-id name_or_arn: The name or ARN of the secret to rotate. Replace name_or_arn with the name or ARN of the secret you want to rotate.
• --rotation-lambda-arn arn_of_lambda_function: The ARN of the Lambda function that performs the secret rotation. Replace arn_of_lambda_function with the ARN of the Lambda function responsible for rotating the secret.

Example Output

{
    "ARN": "arn:aws:secretsmanager:us-east-1:123456789012:secret:my-secret-12345",
    "Name": "my-secret",
    "VersionId": "EXAMPLE1-90ab-cdef-ghij-klmnopqrstuv",
    "VersionStages": [
        "AWSPREVIOUS",
        "AWSCURRENT"
    ]
}

The output confirms that the secret rotation has been triggered successfully.

Use Case 7: Rotate Secret Automatically

Now, let’s see how to configure a secret to rotate automatically every 30 days using a Lambda function.

Code

aws secretsmanager rotate-secret --secret-id name_or_arn --rotation-lambda-arn arn_of_lambda_function --rotation-rules AutomaticallyAfterDays=30

Motivation

Automating secret rotation saves time and effort by ensuring that secrets are regularly rotated without manual intervention. This example demonstrates how to set up automatic secret rotation using a Lambda function with a rotation interval of 30 days.

Explanation

• rotate-secret: This command is used to rotate a secret in the Secrets Manager.

Arguments

• --secret-id name_or_arn: The name or ARN of the secret to rotate. Replace name_or_arn with the name or ARN of the secret you want to rotate.
• --rotation-lambda-arn arn_of_lambda_function: The ARN of the Lambda function that performs the secret rotation. Replace arn_of_lambda_function with the ARN of the Lambda function responsible for rotating the secret.
• --rotation-rules AutomaticallyAfterDays=30: The rotation rules specifying the interval for automatic secret rotation. In this example, the secret will be automatically rotated every 30 days.

Example Output

{
    "ARN": "arn:aws:secretsmanager:us-east-1:123456789012:secret:my-secret-12345",
    "Name": "my-secret",
    "VersionId": "EXAMPLE1-90ab-cdef-ghij-klmnopqrstuv",
    "VersionStages": [
        "AWSPREVIOUS",
        "AWSCURRENT"
    ]
}

The output confirms that the automatic secret rotation has been set up successfully.

Conclusion

In this article, we explored various use cases of the aws secretsmanager command provided by AWS. We covered examples such as listing secrets, creating secrets, deleting secrets, viewing secret details, retrieving secret values, rotating secrets manually, and setting up automatic secret rotation. By understanding and utilizing these commands, you can effectively manage and secure your secrets using AWS Secrets Manager.

Remember to refer to the AWS CLI Secrets Manager documentation for more detailed information and additional options available for the aws secretsmanager command.