AWS::SecretsManager::Secret

The AWS::SecretsManager::Secret resource creates a secret and stores it in Secrets Manager. For more information, see Secret in the AWS Secrets Manager User Guide, and the CreateSecret API in the AWS Secrets Manager API Reference.

To specify the SecretString encrypted value for the secret, specify either the SecretString or the GenerateSecretString property in this resource. You must specify one or the other, but you can't specify both. See the first two examples later in this topic.

Note

You can't generate a secret with a SecretBinary secret value using AWS CloudFormation. You can create only a SecretString text-based secret value.

Note

Do not create a dynamic reference that has a backslash (\) as the final value. AWS CloudFormation cannot resolve those references, which results in a resource failure.

After you create the basic secret, you can do any of the following:

Configure your secret with details of the Secrets Manager supported database or service whose credentials are stored in this secret. After creating the secret, perform these steps in the template:
- Define the database or service. In the definition of the database or service, you can retrieve the credentials in the secret by using the "dynamic reference" syntax that's similar to the following example. Adjust as appropriate for your service. The following YAML example is appropriate for an Amazon RDS MySQL DB instance. It gets the username and password from the SecretString field of the secret named MySecretA. This secret already exists (before running the AWS CloudFormation template) and uses those credentials as the MasterUsername and MasterUserPassword for the new database:
```
    MasterUsername: '{{resolve:secretsmanager:MySecretA:SecretString:username}}'
    MasterUserPassword: '{{resolve:secretsmanager:MySecretA:SecretString:password}}'
```
  Alternatively, if you want to refer to the username and password in a secret that is defined in the same template, then you can use the Ref intrinsic function to retrieve the secret name using the template's logical ID for the secret. The following YAML example shows how to reference components of a secret that is defined somewhere else in the same template. It uses the Fn::Join intrinsic function to concatenate the parts of the string with the retrieved secret values to make the complete argument string.
```
    MasterUsername: !Join ['', ['{{resolve:secretsmanager:', !Ref MySecret, ':SecretString:username}}' ]]
    MasterUserPassword: !Join ['', ['{{resolve:secretsmanager:', !Ref MySecret, ':SecretString:password}}' ]]
```
  The following example shows the same thing in JSON format:
```
    "MasterUsername": {"Fn::Join": [ "", 
["{{resolve:secretsmanager:",{"Ref": "MySecret"},":SecretString:username}}"]
 ] },
    "MasterUserPassword": {"Fn::Join": [
 "", ["{{resolve:secretsmanager:",{"Ref": "MySecret"},":SecretString:password}}"]
 ] },
```
  For more information about using dynamic references to values in other services' resources, see Using Dynamic References to Specify Template Values.
  
  Important
  
  Be careful not to use such resolvable references for sensitive information like the username and password in any location that is logged to avoid accidentally exposing those details. AWS CloudFormation explicitly prevents logging the MasterUsername and MasterUserPassword of an Amazon RDS database instance for this reason.
- Update the secret to add the connection details of the database or service to the secret value. To do this, define a AWS::SecretsManager::SecretTargetAttachment resource and associate it with both the secret and the database or service.
Attach a resource-based permissions policy to the secret. To do this, define a AWS::SecretsManager::ResourcePolicy resource type.
You can optionally configure a secret to rotate after a specified number of days. See AWS::SecretsManager::RotationSchedule.

Topics

Syntax

To declare this entity in your AWS CloudFormation template, use the following syntax:

JSON


{
  "Type" : "AWS::SecretsManager::Secret",
  "Properties" : {
    "Description" : String,
    "KmsKeyId" : String,
    "SecretString" : String,
    "GenerateSecretString" : GenerateSecretString,
    "Tags" : [ Tag, ... ],
    "Name" : String
  }
}

YAML


Type: "AWS::SecretsManager::Secret"
Properties:
  Description: String
  KmsKeyId: String
  SecretString: String
  GenerateSecretString: 
    GenerateSecretString
  Tags: 
    - Tag
  Name: String

Properties

Description

Specifies a user-provided description of the secret.

Required: No

Type: String

Update requires: No interruption

KmsKeyId

Specifies the ARN, Key ID, or alias of the AWS KMS customer master key (CMK) that's used to encrypt the secret values for versions of this secret. If you don't specify this value, then Secrets Manager defaults to the AWS account's default CMK (the one named aws/secretsmanager). If an AWS KMS CMK with that name doesn't yet exist, Secrets Manager creates it for you automatically the first time it needs to encrypt a version's secret value fields.

Required: No

Type: String

Update requires: No interruption

SecretString

Specifies a literal string to use as the secret value in the initial version of this secret. You can specify any text you like, but remember that Lambda rotation functions require a specific JSON structure to be present in this field.

Alternatively, instead of hardcoding the password in this string parameter, we recommend that you use the GenerateSecretString parameter instead.

You must specify either SecretString or GenerateSecretString, but not both.

Required: No

Type: String

Update requires: No interruption

GenerateSecretString

A structure that specifies how to generate a random password by using the functionality of the GetRandomPassword API. You can return that string directly to use as the secret value, or you can alternatively also specify both the SecretStringTemplate and the GenerateSecretKey parameters. Secrets Manager uses the value in GenerateSecretKey as the key name and combines it with the randomly generated password to make a JSON key-value pair. It then inserts that pair into the JSON structure that's specified in the SecretStringTemplate parameter. Secrets Manager stores the completed string as the secret value in the initial version of the secret. For more information about how to use this property, see Secrets Manager Secret GenerateSecretString and the first example in the following Examples section.

You must specify either SecretString or GenerateSecretString, but not both.

Required: No

Type: Secrets Manager Secret GenerateSecretString

Update requires: No interruption

Tags

Specifies an arbitrary set of tags (key–value pairs) to associate with this secret. Use tags to manage your AWS resources.

Required: No

Type: List of Resource Tag property types

Update requires: No interruption

Name

Specifies the friendly name of the new secret. If a Name parameter isn't specified, then Secrets Manager generates a name based on the logical resource ID of the secret in the AWS CloudFormation template.

Required: No

Type: String

Update requires: Replacement

Return Values

Ref

When you pass the logical ID of an AWS::SecretsManager::Secret resource to the intrinsic Ref function, the function returns the ARN of the secret being configured, such as:

arn:aws:secretsmanager:us-west-2:123456789012:secret:my-path/my-secret-name-1a2b3c

This enables you to reference a secret that you create in one part of the stack template from within the definition of another resource later, in the same template. You typically use the Ref function with the AWS::SecretsManager::SecretTargetAttachment resource type to get references to both the secret and its associated database.

For more information about using the Ref function, see Ref.

Examples

Note

The JSON specification doesn't allow any kind of comments. See the YAML example for comments.

Creating a Secret with a Dynamically Generated Password

The following example creates a secret, constructing the secret value from a string template that's combined with a dynamically generated random password. The result of this example is a SecretString value that looks like the following:


{"username": "test-user", "password": "rzDtILsQNfmmHwkJBPsTVhkRvWRtSn" }

For more information, see Secrets Manager Secret GenerateSecretString.

JSON


{
  "MySecretA": {
    "Type": "AWS::SecretsManager::Secret",
    "Properties": {
      "Name": "MySecretForAppA",
      "Description": "This secret has a dynamically generated secret password.",
      "GenerateSecretString": {
        "SecretStringTemplate": "{\"username\":\"test-user\"}",
        "GenerateStringKey": "password",
        "PasswordLength": 30,
        "ExcludeCharacters": "\"@/\\"
      },
      "Tags": [
        {
          "Key": "AppName",
          "Value": "AppA"
        }
      ]
    }
  }
}

YAML


#This is a Secret resource with a randomly generated password in its SecretString JSON.
MySecretA:
  Type: 'AWS::SecretsManager::Secret'
  Properties:
    Name: MySecretForAppA
    Description: "This secret has a dynamically generated secret password."
    GenerateSecretString:
      SecretStringTemplate: '{"username": "test-user"}'
      GenerateStringKey: "password"
      PasswordLength: 30
      ExcludeCharacters: '"@/\'
    Tags:
      -
        Key: AppName
        Value: AppA

Creating a Secret with a Hardcoded Password

The following example creates a secret and provides the secret value as a literal string that's stored in the secret. We recommend that you don't hardcode your password this way. Instead, use the Secrets Manager Secret GenerateSecretString property. See the previous example for that improved option.

JSON


{
  "MySecretB": {
    "Type": "AWS::SecretsManager::Secret",
    "Properties": {
      "Name": "MySecretForAppB",
      "Description": "This secret has a hardcoded password in SecretString (use GenerateSecretString instead)",
      "SecretString": "{\"username\":\"MasterUsername\",\"password\":\"secret-password\"}",
      "Tags": [
        {
          "Key": "AppName",
          "Value": "AppB"
        }
      ]
    }
  }
}

YAML


  # This is another secret that has its password hardcoded into the template (NOT RECOMMENDED)
  MySecretB:
    Type: 'AWS::SecretsManager::Secret'
    Properties:
      Name: MySecretForAppB
      Description: This secret has a hardcoded password in SecretString (use GenerateSecretString instead)
      SecretString: '{"username":"MasterUsername","password":"secret-password"}'
      Tags:
        -
          Key: AppName
          Value: AppB

AWS::SecretsManager::Secret

Syntax

JSON

YAML

Properties

Return Values

Ref

Examples

Creating a Secret with a Dynamically Generated Password

JSON

YAML

Creating a Secret with a Hardcoded Password

JSON

YAML

See Also