💾 Archived View for cfdocs.wetterberg.nu › dynamic-references.gemini captured on 2021-12-04 at 18:04:22. Gemini links have been rewritten to link to archived content
⬅️ Previous capture (2021-12-03)
-=-=-=-=-=-=-
CloudFormation currently supports the following dynamic reference patterns:
Some considerations when using dynamic references:
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.
Dynamic references adhere to the following pattern:
`'{{resolve:service-name:reference-key}}'`
Specifies the service in which the value is stored and managed.
Required.
Currently, valid values include:
AWS Systems Manager Parameter Store
The reference key. Depending on the type of dynamic reference, the reference key may be comprised of multiple segments.
Required.
Use the `ssm` dynamic reference to include values stored in the Systems Manager Parameter Store of type `String` or `StringList` in your templates.
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+}}'`
The name of the parameter in the Systems Manager Parameter Store. The parameter name is case-sensitive.
Required.
An integer that specifies the version of the parameter to use. You must specify the exact version. You cannot currently specify that AWS CloudFormation use the latest version of a parameter. For more information, see Working with parameter versions in the *AWS Systems Manager User Guide*
Required.
Working with parameter versions
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](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_GetParameter.html)` for the specified parameter. For more information, see Controlling access to Systems Manager parameters in the *AWS Systems Manager User Guide*.
Controlling access to Systems Manager parameters
Additional considerations to note when using the `ssm` dynamic reference pattern:
Retrieving the Amazon ECS-optimized AMI metadata
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 in any API call results.
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+}}'`
The name of the parameter in the Systems Manager Parameter Store. The parameter name is case-sensitive.
Required.
An integer that specifies the version of the parameter to use. You must specify the exact version. You cannot currently specify that AWS CloudFormation use the latest version of a parameter. For more information, see Working with parameter versions in the *AWS Systems Manager User Guide*
Required.
Working with parameter versions
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:
Retrieving the Amazon ECS-optimized AMI metadata
Resources that support the `ssm-secure` dynamic reference pattern currently include:
| Resource | Property type | Properties |
| --- | --- | --- |
| AWS::DirectoryService::MicrosoftAD | | `Password` |
| AWS::DirectoryService::SimpleAD | | `Password` |
| AWS::ElastiCache::ReplicationGroup | | `AuthToken` |
| AWS::IAM::User | LoginProfile | `Password` |
| AWS::KinesisFirehose::DeliveryStream | RedshiftDestinationConfiguration | `Password` |
| AWS::OpsWorks::App | Source | `Password` |
| AWS::OpsWorks::Stack | CustomCookbooksSource | `Password` |
| AWS::OpsWorks::Stack | RdsDbInstances | `DbPassword` |
| AWS::RDS::DBCluster | | `MasterUserPassword` |
| AWS::RDS::DBInstance | | `MasterUserPassword` |
| AWS::Redshift::Cluster | | `MasterUserPassword` |
AWS::DirectoryService::MicrosoftAD
AWS::DirectoryService::SimpleAD
AWS::ElastiCache::ReplicationGroup
AWS::KinesisFirehose::DeliveryStream
RedshiftDestinationConfiguration
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*.
You should take the following important security considerations into account when using dynamic parameters to specify Secrets Manager secrets in your stack templates:
Rotating your AWS Secrets Manager secrets
To specify a secret stored in Secrets Manager, you must have access to call `[GetSecretValue](https://docs.aws.amazon.com/secretsmanager/latest/apireference/GetSecretValue.html)` for the specified secret.
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}}`
The name or Amazon Resource Name (ARN) that serves as a unique identifier for the secret.
To access a secret in your AWS account, you need only specify the secret name. To access a secret in a different AWS account, specify the complete ARN of the secret.
Required.
Currently, the only supported value is `SecretString`. The default is `SecretString`.
Specifies the key name of the key-value pair whose value you want to retrieve. If you do not specify a `json-key`, CloudFormation retrieves the entire secret text.
This segment may not include the colon character ( `:` ).
Specifies the secret version that you want to retrieve by the staging label attached to the version. Staging labels are used to keep track of different versions during the rotation process. If you use `version-stage` then don't specify `version-id`. If you don't specify either a version stage or a version ID, then the default is to retrieve the version with the version stage value of `AWSCURRENT`.
This segment may not include the colon character ( `:` ).
Specifies the unique identifier of the version of the secret that you want to use in stack operations. If you specify `version-id`, then don't specify `version-stage`. If you don't specify either a version stage or a version ID, then the default is to retrieve the version with the version stage value of `AWSCURRENT`.
This segment may not include the colon character ( `:` ).
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}}'