Mastering Secrets Management with the AWS Secrets Manager CLI: 21 Powerful Examples for revWhiteShadow

At revWhiteShadow, we understand the critical importance of securely managing sensitive information for your applications. In today’s cloud-native landscape, safeguarding credentials, API keys, certificates, and other confidential data is paramount. While the AWS Management Console offers a visual approach, the AWS Command Line Interface (CLI) provides a powerful, scriptable, and efficient method for interacting with AWS Secrets Manager. This comprehensive guide delves into 21 practical examples designed to showcase the versatility and power of the AWS Secrets Manager CLI, enabling you to manage your secrets with precision and agility.

Understanding the Foundation: AWS Secrets Manager and the CLI

Before we dive into the examples, let’s establish a common understanding. AWS Secrets Manager is a service that helps you protect secrets for applications, services, and IT resources. It enables you to easily rotate, manage, and retrieve database credentials, API keys, and other secrets throughout their lifecycle. By centralizing secret management, you reduce the security risk associated with hardcoding secrets in your code or configuration files.

The AWS CLI, on the other hand, is an open-source tool that enables you to interact with a wide range of AWS services, including Secrets Manager, using commands in your shell. Its command-line nature makes it ideal for automation, scripting, and integration into CI/CD pipelines. For any infrastructure-as-code (IaC) approach, mastering the AWS CLI for secrets management is an essential skill.

Core Operations with AWS Secrets Manager CLI

We’ll begin by exploring the fundamental operations you’ll frequently perform when managing secrets. These examples form the bedrock of your CLI-driven secrets management strategy.

1. Creating a New Secret

The most basic operation is creating a new secret. This command allows you to store any type of sensitive data.

aws secretsmanager create-secret \
    --name my-application/database/credentials \
    --description "Database credentials for my application" \
    --secret-string '{"username":"admin","password":"supersecretpassword123","engine":"mysql","host":"my-db.example.com","port":3306,"dbname":"mydatabase"}'

Explanation:

--name: Assigns a unique, hierarchical name to your secret, making it easily discoverable.
--description: Provides human-readable context about the secret’s purpose.
--secret-string: Stores the actual secret data in a JSON format, which is highly recommended for structured secrets like database credentials. You can also use --secret-file to read from a file.

2. Retrieving a Secret Value

Once a secret is stored, you’ll need to retrieve its value to use in your applications or scripts.

aws secretsmanager get-secret-value \
    --secret-id my-application/database/credentials

Explanation:

--secret-id: Specifies the name or ARN of the secret you wish to retrieve. The output will contain the secret string, which you can then parse or use directly.

3. Listing Available Secrets

To get an overview of the secrets you have stored, the list-secrets command is invaluable.

aws secretsmanager list-secrets \
    --filters Key=tag-key,Values=application \
    --max-results 10

Explanation:

--filters: Allows you to narrow down the results based on various criteria, such as tag keys and values, name prefixes, or creation dates. This is crucial for managing a large number of secrets.
--max-results: Controls the maximum number of secrets to return in a single call, helping manage pagination for extensive secret inventories.

4. Deleting a Secret

When a secret is no longer needed, it’s good practice to delete it to maintain security hygiene.

aws secretsmanager delete-secret \
    --secret-id my-application/database/credentials \
    --recovery-window-in-days 7 \
    --force-delete-without-recovery

Explanation:

--secret-id: The identifier of the secret to be deleted.
--recovery-window-in-days: Specifies a grace period during which the secret can be recovered. This is a safety net against accidental deletion.
--force-delete-without-recovery: If you are absolutely certain and want to bypass the recovery window, use this flag. Use with extreme caution.

5. Describing a Secret

To get metadata about a secret, such as its ARN, description, and rotation status, use the describe-secret command.

aws secretsmanager describe-secret \
    --secret-id my-application/database/credentials

Explanation:

This command provides crucial information about the secret’s configuration and state without revealing the secret value itself.

Advanced Secret Management Techniques with the CLI

Beyond the core operations, AWS Secrets Manager CLI offers sophisticated features for robust secret management.

6. Storing a Secret from a File

For larger or more complex secrets, reading from a file is more manageable than embedding them directly in the command line.

aws secretsmanager create-secret \
    --name my-application/api/keys \
    --description "API keys for third-party service" \
    --secret-file /path/to/your/api_keys.json

Explanation:

--secret-file: Points to a local file containing the secret value. This is particularly useful for JSON or other structured data.

7. Retrieving a Secret as JSON

When dealing with structured secrets, retrieving them in a parseable format is essential.

aws secretsmanager get-secret-value \
    --secret-id my-application/database/credentials \
    --query SecretString \
    --output json | jq .

Explanation:

--query SecretString: Filters the output to only show the SecretString field.
--output json: Ensures the output is in JSON format.
| jq .: This pipes the JSON output to jq, a lightweight and flexible command-line JSON processor, for pretty-printing and easier human readability.

8. Tagging Secrets for Organization

Tags are powerful metadata that help categorize and manage your AWS resources, including secrets.

aws secretsmanager tag-resource \
    --secret-id arn:aws:secretsmanager:us-east-1:123456789012:secret:my-application/database/credentials-AbCdEf \
    --tags Key=environment,Value=production Key=project,Value=webapp

Explanation:

--secret-id: The ARN of the secret to tag.
--tags: A list of key-value pairs for your tags. This is crucial for filtering and organizing secrets, especially in large environments.

9. Removing Tags from a Secret

If you need to change or remove tags, you can do so easily.

aws secretsmanager untag-resource \
    --secret-id arn:aws:secretsmanager:us-east-1:123456789012:secret:my-application/database/credentials-AbCdEf \
    --tag-keys environment

Explanation:

--tag-keys: Specifies the keys of the tags to remove.

10. Enabling Secret Rotation

Automated secret rotation is a core feature of AWS Secrets Manager, and the CLI allows you to configure it. This example assumes you have a Lambda function set up for rotation.

aws secretsmanager rotate-secret \
    --secret-id my-application/database/credentials \
    --rotation-lambda-arn arn:aws:lambda:us-east-1:123456789012:function:MySecretRotationFunction

Explanation:

--secret-id: The target secret.
--rotation-lambda-arn: The ARN of the AWS Lambda function responsible for rotating the secret. Secrets Manager will invoke this function to perform the rotation.

11. Configuring Rotation Schedule

You can define how often your secrets should be rotated.

aws secretsmanager update-secret \
    --secret-id my-application/database/credentials \
    --rotation-rules Fn=hours,Coverage=24 --rotation-lambda-arn arn:aws:lambda:us-east-1:123456789012:function:MySecretRotationFunction

Explanation:

--rotation-rules: Defines the rotation schedule. Here, Fn=hours,Coverage=24 means the rotation will occur every 24 hours. You can also specify days.
--rotation-lambda-arn: The Lambda function to use for rotation.

12. Disabling Secret Rotation

If you need to temporarily or permanently stop automatic rotation, you can disable it.

aws secretsmanager update-secret \
    --secret-id my-application/database/credentials \
    --no-rotate

Explanation:

--no-rotate: This flag effectively disables the automatic rotation for the specified secret.

13. Replicating Secrets to Other Regions

For disaster recovery and high availability, replicating secrets across AWS regions is a best practice.

aws secretsmanager replicate-secret-to-regions \
    --secret-id arn:aws:secretsmanager:us-east-1:123456789012:secret:my-application/database/credentials-AbCdEf \
    --region-configurations '{"us-west-2":{"KmsKeyId":"arn:aws:kms:us-west-2:123456789012:key/your-kms-key-id"}}'

Explanation:

--secret-id: The ARN of the primary secret.
--region-configurations: A JSON string specifying the target regions and optionally the KMS key to use for encryption in those regions.

14. Removing a Secret Replication

You can also remove replication from a specific region.

aws secretsmanager delete-secret-replication \
    --secret-id arn:aws:secretsmanager:us-east-1:123456789012:secret:my-application/database/credentials-AbCdEf \
    --region us-west-2

Explanation:

--secret-id: The ARN of the secret.
--region: The specific region from which to remove the replication.

Scripting and Automation with the CLI

The true power of the AWS CLI lies in its ability to be integrated into scripts for automated workflows.

15. Batch Retrieving Secrets for an Application

Imagine an application that needs multiple secrets. You can automate fetching them.

#!/bin/bash

SECRETS=("my-application/database/credentials" "my-application/api/keys" "my-application/config/settings")

for secret_name in "${SECRETS[@]}"; do
    echo "Retrieving secret: $secret_name"
    secret_value=$(aws secretsmanager get-secret-value --secret-id "$secret_name" --query SecretString --output text)
    if [ $? -eq 0 ]; then
        echo "$secret_name retrieved successfully."
        # Process secret_value here (e.g., export as environment variables)
        # Example: export $(echo "$secret_value" | jq -r 'to_entries[] | "APP_\(.key|ascii_upcase)=\(.value)"')
    else
        echo "Failed to retrieve secret: $secret_name"
    fi
done

Explanation:

This script iterates through a predefined array of secret names, retrieves each one, and provides a placeholder for further processing. This is a foundational pattern for application startup scripts.

16. Automating Secret Creation in a Pipeline

When deploying new services, you might need to create secrets dynamically.

#!/bin/bash

SECRET_NAME="my-new-service/api-key"
SECRET_JSON='{"api_key": "generated_key_value"}' # In a real scenario, this would be generated.

aws secretsmanager create-secret \
    --name "$SECRET_NAME" \
    --description "API key for my new service" \
    --secret-string "$SECRET_JSON" \
    --tags Key=environment,Value=development Key=service,Value=new-service

if [ $? -eq 0 ]; then
    echo "Secret '$SECRET_NAME' created successfully."
else
    echo "Failed to create secret '$SECRET_NAME'."
    exit 1
fi

Explanation:

This script demonstrates creating a secret with specific naming conventions and tags, crucial for automated deployments in CI/CD.

17. Updating a Secret Value with a New Value

You might need to update a secret manually or as part of a process.

aws secretsmanager update-secret \
    --secret-id my-application/database/credentials \
    --secret-string '{"username":"newadmin","password":"newsupersecretpassword456","engine":"mysql","host":"my-db.example.com","port":3306,"dbname":"mydatabase"}'

Explanation:

This command replaces the entire SecretString with the new value provided.

18. Updating a Secret Description

You can modify the description of a secret without affecting its value.

aws secretsmanager update-secret \
    --secret-id my-application/database/credentials \
    --description "Updated database credentials for production environment"

Explanation:

This allows you to refine the metadata associated with your secrets as your understanding or application requirements evolve.

Working with Different Secret Types

AWS Secrets Manager isn’t just for key-value pairs; it’s versatile enough for various sensitive data types.

19. Storing and Retrieving Binary Secrets (e.g., SSL Certificates)

For binary data like SSL certificates or private keys, you can store them as base64 encoded strings or directly from files.

To create a binary secret:

First, base64 encode your certificate file:

CERT_BASE64=$(base64 -w 0 /path/to/your/certificate.pem)
KEY_BASE64=$(base64 -w 0 /path/to/your/private.key)

# Combine them into a JSON or a simple string as per your application's needs.
# For this example, we'll store them as separate fields within a JSON.
SECRET_JSON="{\"certificate\": \"$CERT_BASE64\", \"private_key\": \"$KEY_BASE64\"}"

Then, create the secret:

aws secretsmanager create-secret \
    --name my-application/ssl/certificate \
    --description "SSL certificate and private key" \
    --secret-string "$SECRET_JSON"

To retrieve and decode the binary secret:

SECRET_JSON_OUTPUT=$(aws secretsmanager get-secret-value --secret-id my-application/ssl/certificate --query SecretString --output text)

# Decode and save to files
echo "$SECRET_JSON_OUTPUT" | jq -r '.certificate' | base64 --decode > certificate.pem
echo "$SECRET_JSON_OUTPUT" | jq -r '.private_key' | base64 --decode > private.key

echo "Certificate and private key saved to certificate.pem and private.key"

Explanation:

This demonstrates a common use case for storing TLS/SSL certificates and private keys. The --secret-string can hold a JSON object with keys like certificate and private_key, which are then base64 encoded.

20. Versioning of Secrets

AWS Secrets Manager automatically versions your secrets when you update them. You can retrieve previous versions.

aws secretsmanager get-secret-value \
    --secret-id my-application/database/credentials \
    --version-stage AWSPREVIOUS

Explanation:

--version-stage AWSPREVIOUS: Retrieves the most recent previous version of the secret. Other stages like AWSCURRENT and NULL are also available. This is useful for rollbacks or auditing.

21. Creating Secrets with KMS Encryption Key Configuration

While AWS Secrets Manager defaults to using an AWS-managed KMS key, you can specify your own customer-managed KMS key for greater control.

aws secretsmanager create-secret \
    --name my-application/secure-config \
    --description "Sensitive configuration data encrypted with custom KMS key" \
    --secret-string '{"encryption_key":"AES-256"}' \
    --kms-key-id arn:aws:kms:us-east-1:123456789012:key/your-custom-kms-key-id

Explanation:

--kms-key-id: Specifies the ARN of the customer-managed KMS key to use for encrypting the secret. This gives you more granular control over encryption policies and key rotation.

Best Practices and Next Steps

When leveraging the AWS Secrets Manager CLI, remember these best practices:

Use Hierarchical Naming: Employ a consistent naming convention (e.g., application/environment/resource/secret_type) to make secrets easy to locate and manage.
Leverage Tags Extensively: Tag your secrets by application, environment, team, or any other relevant metadata to facilitate filtering and access control.
Automate Rotation: Always enable automatic rotation for credentials like database passwords to enhance security.
Implement Least Privilege: When granting access to secrets, use IAM policies to ensure users and applications only have the permissions they strictly need.
Secure Your CLI Credentials: Ensure the AWS credentials used by the CLI are themselves securely managed, ideally through IAM roles for EC2 instances or ECS tasks.
Integrate with CI/CD: Automate secret creation, retrieval, and updates within your CI/CD pipelines to ensure secure and consistent deployments.

By mastering these 21 examples of the AWS Secrets Manager CLI, you are well-equipped to implement a robust and secure secrets management strategy for your applications. At revWhiteShadow, we believe that understanding and utilizing these powerful tools is key to building secure, resilient, and efficient cloud infrastructure. Continue to explore the capabilities of the AWS CLI, and you’ll unlock even greater levels of automation and security for your sensitive data.

21 Examples to Manage Secrets using AWS Secrets Manager CLI

Mastering Secrets Management with the AWS Secrets Manager CLI: 21 Powerful Examples for revWhiteShadow #

Understanding the Foundation: AWS Secrets Manager and the CLI #

Core Operations with AWS Secrets Manager CLI #

1. Creating a New Secret #

2. Retrieving a Secret Value #

3. Listing Available Secrets #

4. Deleting a Secret #

5. Describing a Secret #

Advanced Secret Management Techniques with the CLI #

6. Storing a Secret from a File #

7. Retrieving a Secret as JSON #

8. Tagging Secrets for Organization #

9. Removing Tags from a Secret #

10. Enabling Secret Rotation #

11. Configuring Rotation Schedule #

12. Disabling Secret Rotation #

13. Replicating Secrets to Other Regions #

14. Removing a Secret Replication #

Scripting and Automation with the CLI #

15. Batch Retrieving Secrets for an Application #

16. Automating Secret Creation in a Pipeline #

17. Updating a Secret Value with a New Value #

18. Updating a Secret Description #

Working with Different Secret Types #

19. Storing and Retrieving Binary Secrets (e.g., SSL Certificates) #

20. Versioning of Secrets #

21. Creating Secrets with KMS Encryption Key Configuration #

Best Practices and Next Steps #

Mastering Secrets Management with the AWS Secrets Manager CLI: 21 Powerful Examples for revWhiteShadow

Understanding the Foundation: AWS Secrets Manager and the CLI

Core Operations with AWS Secrets Manager CLI

1. Creating a New Secret

2. Retrieving a Secret Value

3. Listing Available Secrets

4. Deleting a Secret

5. Describing a Secret

Advanced Secret Management Techniques with the CLI

6. Storing a Secret from a File

7. Retrieving a Secret as JSON

8. Tagging Secrets for Organization

9. Removing Tags from a Secret

10. Enabling Secret Rotation

11. Configuring Rotation Schedule

12. Disabling Secret Rotation

13. Replicating Secrets to Other Regions

14. Removing a Secret Replication

Scripting and Automation with the CLI

15. Batch Retrieving Secrets for an Application

16. Automating Secret Creation in a Pipeline

17. Updating a Secret Value with a New Value

18. Updating a Secret Description

Working with Different Secret Types

19. Storing and Retrieving Binary Secrets (e.g., SSL Certificates)

20. Versioning of Secrets

21. Creating Secrets with KMS Encryption Key Configuration

Best Practices and Next Steps