AWS CDK AWS Secrets Manager (v1)

Common errors

• ModuleNotFoundError: No module named 'aws_cdk.aws_secretsmanager'

  cause The `aws-cdk.aws-secretsmanager` package has not been installed, or you are trying to use v1 import paths with a v2 (`aws-cdk-lib`) installation.
  fix Ensure you have `aws-cdk.core` and `aws-cdk.aws-secretsmanager` installed for v1: `pip install aws-cdk.core aws-cdk.aws-secretsmanager`. If you intend to use v2, switch to `aws-cdk-lib` and update your import statements (e.g., `from aws_cdk import aws_secretsmanager`).

• AttributeError: module 'aws_cdk.aws_secretsmanager' has no attribute 'Secret'

  cause You likely have AWS CDK v2 (`aws-cdk-lib`) installed but are attempting to use import syntax or class names from AWS CDK v1, or there's a typo in the class name.
  fix Verify your `pip freeze` output to confirm the installed CDK version. If on v2, use `from aws_cdk import aws_secretsmanager` and access `secretsmanager.Secret`. If on v1, ensure the `aws-cdk.aws-secretsmanager` package is installed and your imports are correct as shown in the quickstart.

• TypeError: Expected token, got <class 'str'>

  cause You are attempting to pass a raw string directly to a CDK construct property that expects a secret token or reference (e.g., `secret.secret_value.to_string()`).
  fix When referencing secret values for CloudFormation properties, use the appropriate method to convert the secret value token: `my_secret.secret_value.to_string()` or `my_secret.secret_value_from_json('username').to_string()` for specific JSON fields.

Warnings

• breaking AWS CDK v1 (`aws-cdk.aws-secretsmanager`) is a separate major version from AWS CDK v2 (`aws-cdk-lib`). V1 packages are not compatible with V2. New projects should generally start with V2.
  Fix: For new projects, use `aws-cdk-lib` and its corresponding import paths (e.g., `from aws_cdk import aws_secretsmanager`). For existing v1 projects, refer to the AWS CDK migration guide for upgrading to v2.
• gotcha Retrieving secret values in plaintext requires careful handling. `secret.secret_value` returns a token (e.g., `CfnDynamicReference`), not the actual plaintext value, during synthesis. To use the value, you often need `secret.secret_value.to_string()` for CloudFormation parameters, or you must retrieve it at application runtime.
  Fix: Use `secret.secret_value.to_string()` or `secret.secret_value.unsafe_unwrap()` when passing the value to other CloudFormation resources (e.g., environment variables for Lambda). For runtime retrieval, your application code (e.g., Lambda, EC2) must use the AWS SDK to fetch the secret's value by its ARN or name.
• gotcha Configuring automatic secret rotation for services like RDS, Redshift, or DocumentDB requires a custom Lambda function and appropriate permissions, which need to be explicitly defined in your CDK stack. The `add_rotation_schedule` method helps but still relies on these underlying resources.
  Fix: Ensure the required Lambda function, IAM roles, and permissions are correctly set up and associated with the secret's rotation schedule. Refer to the AWS CDK documentation for specific service integration examples (e.g., `Secret.add_rotation_schedule()` and `RotationSchedule.add_target()`).

Install

• pip install aws-cdk.core aws-cdk.aws-secretsmanager Install for AWS CDK v1
• pip install aws-cdk-lib Install for AWS CDK v2 (recommended for new projects)

Imports

• Secret
  wrong:

  from aws_cdk import secretsmanager

  correct:

  from aws_cdk import aws_secretsmanager
  # or
  from aws_cdk.aws_secretsmanager import Secret

  In AWS CDK v1, service constructs modules are prefixed with `aws_` (e.g., `aws_secretsmanager`), not just the service name.

Quickstart

This quickstart demonstrates how to define a new secret using `aws-cdk.aws-secretsmanager`. It creates a secret with a generated random password, which is a common pattern for database credentials or API keys. Remember that sensitive values should not be hardcoded directly into your CDK code.

from aws_cdk import App, Stack, aws_secretsmanager as secretsmanager
from constructs import Construct

class MySecretsStack(Stack):
    def __init__(self, scope: Construct, construct_id: str, **kwargs) -> None:
        super().__init__(scope, construct_id, **kwargs)

        # Define a new secret with a generated password
        my_app_secret = secretsmanager.Secret(self, "MyAppSecret",
            description="A secret for my application",
            generate_secret_string=secretsmanager.SecretStringGenerator(
                password_length=20,
                exclude_characters='@/" '
            )
        )

        # You can also define a secret with a specific value (e.g., loaded from env var)
        # Note: Avoid hardcoding sensitive values directly
        # my_static_secret = secretsmanager.Secret(self, "MyStaticSecret",
        #     secret_string="my-super-secret-value"
        # )

        # To reference the secret ARN, for example, for a policy or output
        # print(f"Secret ARN: {my_app_secret.secret_arn}")

app = App()
MySecretsStack(app, "MySecretsStackExample")
app.synth()