Using Dynamic References to Specify Template Values

Dynamic references provide a compact, powerful way for you to specify external values that are stored and managed in other services, such as the Systems Manager Parameter Store, in your stack templates. When you use a dynamic reference, CloudFormation retrieves the value of the specified reference when necessary during stack and change set operations.

CloudFormation currently supports the following dynamic reference patterns:

Some considerations when using dynamic references:

Specifying Dynamic References in Stack Templates

Dynamic references adhere to the following pattern:

'{{resolve:service-name:reference-key}}'

SSM Parameters

Use the ssm dynamic reference to include values stored in the Systems Manager Parameter Store of type String or StringList in your templates.

Reference Pattern

For SSM Parameters, the reference-key segment is composed of the parameter name and version number. Use the following pattern:

'{{resolve:ssm:parameter-name:version}}'

Your reference must adhere to the following regular expression pattern for parameter-name and version:

'{{resolve:ssm:[a-zA-Z0-9_.-/]+:\\d+}}'

Example

The following example uses an ssm dynamic reference to set the access control for an S3 bucket to a parameter value stored in Systems Manager Parameter Store. As specified, CloudFormation will use version 2 of the S3AccessControl parameter for stack and change set operations.

  "MyS3Bucket": {
    "Type": "AWS::S3::Bucket",
    "Properties": {
      "AccessControl": "{{resolve:ssm:S3AccessControl:2}}""
    }
  }

  MyS3Bucket:
    Type: 'AWS::S3::Bucket'
    Properties:
      AccessControl: '{{resolve:ssm:S3AccessControl:2}}' 

To specify a parameter stored in the Systems Manager Parameter Store, you must have access to call GetParameters for the specified parameter. For more information, see Controlling Access to Systems Manager Parameters in the AWS Systems Manager User Guide.

Additional considerations to note when using the ssm dynamic reference pattern:

SSM Secure String Parameters

Use the ssm-secure dynamic reference pattern to specify AWS Systems Manager SecureString type parameters in your templates. For ssm-secure dynamic references, AWS CloudFormation never stores the actual parameter value. AWS CloudFormation accesses the parameter value during create and update operations for stacks and change sets. Currently, secure string parameters can only be used for resource properties that support the ssm-secure dynamic reference pattern.

A secure string parameter is any sensitive data that needs to be stored and referenced in a secure manner. That is, data that you don't want users to alter or reference in clear text, such as passwords or license keys. For more information on secure strings, see Use Secure String Parameters in the AWS Systems Manager User Guide.

Secure string parameters values are not stored in CloudFormation, nor are they returned as part of in any API call results.

Reference Pattern

For ssm-secure dynamic references, the reference-key segment is composed of the parameter name and version number. Use the following pattern:

'{{resolve:ssm-secure:parameter-name:version}}'

Your reference must adhere to the following regular expression pattern for parameter-name and version:

'{{resolve:ssm-secure:[a-zA-Z0-9_.-/]+:\\d+}}'

Example

The following example uses an ssm-secure dynamic reference to set the password for an IAM user to a secure string stored in Systems Manager Parameter Store. As specified, CloudFormation will use version 10 of the IAMUserPassword parameter for stack and change set operations.

  "MyIAMUser": {
    "Type": "AWS::IAM::User",
    "Properties": {
      "UserName": "MyUserName",
      "LoginProfile": {
        "Password": "{{resolve:ssm-secure:IAMUserPassword:10}}"
      }
    }
  }

  MyIAMUser:
    Type: AWS::IAM::User
    Properties:
      UserName: 'MyUserName'
      LoginProfile:
        Password: '{{resolve:ssm-secure:IAMUserPassword:10}}'

Additional considerations to note when using the ssm-secure dynamic reference pattern:

Resources that Support Dynamic Parameter Patterns for Secure Strings

Resources that support the ssm-secure dynamic reference pattern currently include:

Secrets Manager Secrets

Use the secretsmanager dynamic reference to retrieve entire secrets or secret values that are stored in AWS Secrets Manager for use in your templates. Secrets can be database credentials, passwords, third-party API keys, and even arbitrary text. Using Secrets Manager, you can store and control access to these secrets centrally. Secrets Manager enables you to replace hardcoded credentials in your code (including passwords), with an API call to Secrets Manager to retrieve the secret programmatically. For more information, see see What Is AWS Secrets Manager? in the AWS Secrets Manager User Guide.

To specify a secret stored in Secrets Manager, you must have access to call GetSecretValue for the specified secret.

Dynamic references for secure values, such as secretsmanager, are not currently supported in custom resources.

Reference Pattern

For Secrets Manager secrets, the reference-key segment is composed of several segments, including the secret id, secret value key, version stage, and version id. Use the following pattern:

{{resolve:secretsmanager:secret-id:secret-string:json-key:version-stage:version-id}}

Examples

The following example uses the secret-name and json-key segments to retrieve the username and password values stored in the MyRDSSecret secret. By default, the secret version retrieved is the version with the version stage value of AWSCURRENT.

{
    "MyRDSInstance": {
        "Type": "AWS::RDS::DBInstance",
        "Properties": {
            "DBName": "MyRDSInstance",
            "AllocatedStorage": "20",
            "DBInstanceClass": "db.t2.micro",
            "Engine": "mysql",
            "MasterUsername": "{{resolve:secretsmanager:MyRDSSecret:SecretString:username}}",
            "MasterUserPassword": "{{resolve:secretsmanager:MyRDSSecret:SecretString:password}}"
        }
    }
}

  MyRDSInstance:
    Type: 'AWS::RDS::DBInstance'
    Properties:
      DBName: MyRDSInstance
      AllocatedStorage: '20'
      DBInstanceClass: db.t2.micro
      Engine: mysql
      MasterUsername: '{{resolve:secretsmanager:MyRDSSecret:SecretString:username}}'
      MasterUserPassword: '{{resolve:secretsmanager:MyRDSSecret:SecretString:password}}'

Specifying the following segments would retrieve the entire SecretString field for the version of the MySecret secret with the version stage value of AWSCURRENT.

  '{{resolve:secretsmanager:MySecret}}' or '{{resolve:secretsmanager:MySecret::::}}'

Specifying the following segments would retrieve the password value for the version of the MySecret SecretString with the version stage value of AWSCURRENT.

  '{{resolve:secretsmanager:MySecret:SecretString:password}}'

Specifying the following segments would retrieve the password value for the version of the MySecret secret with the version ID of EXAMPLE1-90ab-cdef-fedc-ba987EXAMPLE.

  '{{resolve:secretsmanager:MySecret:SecretString:password:SecretString:EXAMPLE1-90ab-cdef-fedc-ba987EXAMPLE}}'

Specifying the following segments would retrieve the entire SecretString for the version of the MySecret secret with the version stage value of AWSCURRENT from another AWS account. Note that you must specify the complete secret ARN to access secrets in another AWS account.

  '{{resolve:secretsmanager:arn:aws:secretsmanager:us-west-2:123456789012:secret:MySecret-asd123}}'

Specifying the following segments would retrieve the password value for the version of the MySecret secret with the version stage value of AWSCURRENT from another AWS account. Note that you must specify the complete secret ARN to access secrets in another AWS account.

  '{{resolve:secretsmanager:arn:aws:secretsmanager:us-west-2:123456789012:secret:MySecret-asd123:SecretString:password}}'

Specifying the following segments would retrieve the the password value for the version of the MySecret secret with the version stage value of AWSPENDING from another AWS account. Note that you must specify the complete secret ARN to access secrets in another AWS account.

  '{{resolve:secretsmanager:arn:aws:secretsmanager:us-west-2:123456789012:secret:MySecretName-asd123:SecretString:password:AWSPENDING}}'

On this page:

• Specifying Dynamic References in Stack Templates
• SSM Parameters
• SSM Secure String Parameters
• Secrets Manager Secrets