Package: aws-cdk.aws-secretsmanager
AWS Secrets Manager Construct Library---AWS CDK v1 has reached End-of-Support on 2023-06-01.
This package is no longer being updated, and users should migrate to AWS CDK v2.For more information on how to migrate, see theMigrating to AWS CDK v2guide.importaws_cdk.aws_secretsmanagerassecretsmanagerCreate a new Secret in a StackIn order to have SecretsManager generate a new secret value automatically,
you can get started with the following:# Default secretsecret=secretsmanager.Secret(self,"Secret")# Using the default secretiam.User(self,"User",password=secret.secret_value)# Templated secrettemplated_secret=secretsmanager.Secret(self,"TemplatedSecret",generate_secret_string=secretsmanager.SecretStringGenerator(secret_string_template=JSON.stringify({"username":"user"}),generate_string_key="password"))# Using the templated secretiam.User(self,"OtherUser",user_name=templated_secret.secret_value_from_json("username").to_string(),password=templated_secret.secret_value_from_json("password"))If you need to use a pre-existing secret, the recommended way is to manually
provision the secret inAWS SecretsManagerand use theSecret.fromSecretArnorSecret.fromSecretAttributesmethod to make it available in your CDK Application:# encryption_key: kms.Keysecret=secretsmanager.Secret.from_secret_attributes(self,"ImportedSecret",secret_arn="arn:aws:secretsmanager:<region>:<account-id-number>:secret:<secret-name>-<random-6-characters>",# If the secret is encrypted using a KMS-hosted CMK, either import or reference that key:encryption_key=encryption_key)SecretsManager secret values can only be used in select set of properties. For the
list of properties, seethe CloudFormation Dynamic References documentation.A secret can setRemovalPolicy. If it set toRETAIN, that removing a secret will fail.Grant permission to use the secret to a roleYou must grant permission to a resource for that resource to be allowed to
use a secret. This can be achieved with theSecret.grantReadand/orSecret.grantWritemethod, depending on your need:role=iam.Role(self,"SomeRole",assumed_by=iam.AccountRootPrincipal())secret=secretsmanager.Secret(self,"Secret")secret.grant_read(role)secret.grant_write(role)If, as in the following example, your secret was created with a KMS key:# role: iam.Rolekey=kms.Key(self,"KMS")secret=secretsmanager.Secret(self,"Secret",encryption_key=key)secret.grant_read(role)secret.grant_write(role)thenSecret.grantReadandSecret.grantWritewill also grant the role the
relevant encrypt and decrypt permissions to the KMS key through the
SecretsManager service principal.The principal is automatically added to Secret resource policy and KMS Key policy for cross account access:other_account=iam.AccountPrincipal("1234")key=kms.Key(self,"KMS")secret=secretsmanager.Secret(self,"Secret",encryption_key=key)secret.grant_read(other_account)Rotating a SecretUsing a Custom Lambda FunctionA rotation schedule can be added to a Secret using a custom Lambda function:importaws_cdk.aws_lambdaaslambda_# fn: lambda.Functionsecret=secretsmanager.Secret(self,"Secret")secret.add_rotation_schedule("RotationSchedule",rotation_lambda=fn,automatically_after=Duration.days(15))Note: The required permissions for Lambda to call SecretsManager and the other way round are automatically granted based onAWS Documentationas long as the Lambda is not imported.SeeOverview of the Lambda Rotation Functionon how to implement a Lambda Rotation Function.Using a Hosted Lambda FunctionUse thehostedRotationprop to rotate a secret with a hosted Lambda function:secret=secretsmanager.Secret(self,"Secret")secret.add_rotation_schedule("RotationSchedule",hosted_rotation=secretsmanager.HostedRotation.mysql_single_user())Hosted rotation is available for secrets representing credentials for MySQL, PostgreSQL, Oracle,
MariaDB, SQLServer, Redshift and MongoDB (both for the single and multi user schemes).When deployed in a VPC, the hosted rotation implementsec2.IConnectable:# my_vpc: ec2.Vpc# db_connections: ec2.Connections# secret: secretsmanager.Secretmy_hosted_rotation=secretsmanager.HostedRotation.mysql_single_user(vpc=my_vpc)secret.add_rotation_schedule("RotationSchedule",hosted_rotation=my_hosted_rotation)db_connections.allow_default_port_from(my_hosted_rotation)See alsoAutomating secret creation in AWS CloudFormation.Rotating database credentialsDefine aSecretRotationto rotate database credentials:# my_secret: secretsmanager.Secret# my_database: ec2.IConnectable# my_vpc: ec2.Vpcsecretsmanager.SecretRotation(self,"SecretRotation",application=secretsmanager.SecretRotationApplication.MYSQL_ROTATION_SINGLE_USER,# MySQL single user schemesecret=my_secret,target=my_database,# a Connectablevpc=my_vpc,# The VPC where the secret rotation application will be deployedexclude_characters=" %+:;{}")The secret must be a JSON string with the following format:{"engine":"<required: database engine>","host":"<required: instance host name>","username":"<required: username>","password":"<required: password>","dbname":"<optional: database name>","port":"<optional: if not specified, default port will be used>","masterarn":"<required for multi user rotation: the arn of the master secret which will be used to create users/change passwords>"}For the multi user scheme, amasterSecretmust be specified:# my_user_secret: secretsmanager.Secret# my_master_secret: secretsmanager.Secret# my_database: ec2.IConnectable# my_vpc: ec2.Vpcsecretsmanager.SecretRotation(self,"SecretRotation",application=secretsmanager.SecretRotationApplication.MYSQL_ROTATION_MULTI_USER,secret=my_user_secret,# The secret that will be rotatedmaster_secret=my_master_secret,# The secret used for the rotationtarget=my_database,vpc=my_vpc)See alsoaws-rdswhere
credentials generation and rotation is integrated.Importing SecretsExisting secrets can be imported by ARN, name, and other attributes (including the KMS key used to encrypt the secret).
Secrets imported by name should use the short-form of the name (without the SecretsManager-provided suffx);
the secret name must exist in the same account and region as the stack.
Importing by name makes it easier to reference secrets created in different regions, each with their own suffix and ARN.secret_complete_arn="arn:aws:secretsmanager:eu-west-1:111111111111:secret:MySecret-f3gDy9"secret_partial_arn="arn:aws:secretsmanager:eu-west-1:111111111111:secret:MySecret"# No Secrets Manager suffixencryption_key=kms.Key.from_key_arn(self,"MyEncKey","arn:aws:kms:eu-west-1:111111111111:key/21c4b39b-fde2-4273-9ac0-d9bb5c0d0030")my_secret_from_complete_arn=secretsmanager.Secret.from_secret_complete_arn(self,"SecretFromCompleteArn",secret_complete_arn)my_secret_from_partial_arn=secretsmanager.Secret.from_secret_partial_arn(self,"SecretFromPartialArn",secret_partial_arn)my_secret_from_name=secretsmanager.Secret.from_secret_name_v2(self,"SecretFromName","MySecret")my_secret_from_attrs=secretsmanager.Secret.from_secret_attributes(self,"SecretFromAttributes",secret_complete_arn=secret_complete_arn,encryption_key=encryption_key)Replicating secretsSecrets can be replicated to multiple regions by specifyingreplicaRegions:# my_key: kms.Keysecretsmanager.Secret(self,"Secret",replica_regions=[secretsmanager.ReplicaRegion(region="eu-west-1"),secretsmanager.ReplicaRegion(region="eu-central-1",encryption_key=my_key)])Alternatively, useaddReplicaRegion():secret=secretsmanager.Secret(self,"Secret")secret.add_replica_region("eu-west-1")