# Get values stored in other services using dynamic references
Dynamic references provide a convenient way for you to specify external values stored and managed in other services and decouple sensitive information from your infrastructure-as-code templates. CloudFormation retrieves the value of the specified reference when necessary during stack and change set operations.
With dynamic references, you can:
+ **Use secure strings** – For sensitive data, always use secure string parameters in AWS Systems Manager Parameter Store or secrets in AWS Secrets Manager to ensure your data is encrypted at rest.
+ **Limit access** – Restrict access to the Parameter Store parameters or Secrets Manager secrets to only authorized principals and roles.
+ **Rotate credentials** – Regularly rotate your sensitive data stored in Parameter Store or Secrets Manager to maintain a high level of security.
+ **Automate rotation** – Leverage the automatic rotation features of Secrets Manager to periodically update and distribute your sensitive data across your applications and environments.
## General considerations
The following are the general considerations for you to consider before you specify dynamic references in your CloudFormation templates:
+ Avoid including dynamic references, or any sensitive data, in resource properties that are part of a resource's primary identifier. CloudFormation may use the actual plaintext value in the primary resource identifier, which could be a security risk. This resource ID may appear in any derived outputs or destinations.
To determine which resource properties comprise a resource type's primary identifier, refer to the resource reference documentation for that resource in [AWS resource and property types reference](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-template-resource-type-ref.html). In the **Return values** section, the `Ref` function return value represents the resource properties that comprise the resource type's primary identifier.
+ You can include up to 60 dynamic references in a stack template.
+ If you're using transforms (like `AWS::Include` or `AWS::Serverless`), CloudFormation doesn't resolve dynamic references before applying the transform. Instead, it passes the literal string of the dynamic reference to the transform, and resolves the references when you execute the change set using the template.
+ Dynamic references can't be used for secure values (like those stored in Parameter Store or Secrets Manager) in custom resources.
+ Dynamic references are also not supported in `AWS::CloudFormation::Init` metadata and Amazon EC2 `UserData` properties.
+ Don't create a dynamic reference that ends with a backslash (\$1). CloudFormation can't resolve these references, which will cause stack operations to fail.
The following topics provide information and other considerations for using dynamic references.
**Topics**
+ [
## General considerations
](#dynamic-references-considerations)
+ [
# Get a plaintext value from Systems Manager Parameter Store
](dynamic-references-ssm.md)
+ [
# Get a secure string value from Systems Manager Parameter Store
](dynamic-references-ssm-secure-strings.md)
+ [
# Get a secret or secret value from Secrets Manager
](dynamic-references-secretsmanager.md)
# Get a plaintext value from Systems Manager Parameter Store
When you're creating a CloudFormation template, you might want to use plaintext values stored in Parameter Store. Parameter Store is a capability of AWS Systems Manager. For an introduction to Parameter Store, see [AWS Systems Manager Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html) in the *AWS Systems Manager User Guide*.
To use a plaintext value from Parameter Store within your template, you use a `ssm` dynamic reference. This reference allows you to access values from parameters of type `String` or `StringList` in Parameter Store.
To verify which version of an `ssm` dynamic reference will be used in a stack operation, create a change set for the stack operation. Then, review the processed template on the **Template** tab. For more information, see [Create a change set for a CloudFormation stack](using-cfn-updating-stacks-changesets-create.md).
When using `ssm` dynamic references, there are a few important things to keep in mind:
+ CloudFormation doesn't support drift detection on dynamic references. For `ssm` dynamic references where you haven't specified the parameter version, we recommend that, if you update the parameter version in Systems Manager, you also perform a stack update operation on any stacks that include the `ssm` dynamic reference, in order to fetch the latest parameter version.
+ To use a `ssm` dynamic reference in the `Parameters` section of your CloudFormation template, you must include a version number. CloudFormation doesn't allow you to reference a Parameter Store value without a version number in this section. Alternatively, you can define your parameter as a Systems Manager parameter type in your template. When you do this, you can specify a Systems Manager parameter key as the default value for your parameter. CloudFormation will then retrieve the latest version of the parameter value from Parameter Store, without you having to specify a version number. This can make your templates simpler and easier to maintain. For more information, see [Specify existing resources at runtime with CloudFormation-supplied parameter types](cloudformation-supplied-parameter-types.md).
+ For custom resources, CloudFormation resolves the `ssm` dynamic references before sending the request to the custom resource.
+ CloudFormation doesn't support using dynamic references to reference a parameter shared from another AWS account.
+ CloudFormation doesn't support using Systems Manager parameter labels in dynamic references.
## Permissions
To specify a parameter stored in the Systems Manager Parameter Store, you must have permission to call [https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_GetParameter.html](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_GetParameter.html) for the specified parameter. To learn how to create IAM policies that provide access to specific Systems Manager parameters, see [Restricting access to Systems Manager parameters using IAM policies](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-paramstore-access.html) in the *AWS Systems Manager User Guide*.
## Reference pattern
To reference a plaintext value stored in Systems Manager Parameter Store in your CloudFormation template, use the following `ssm` reference 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+)?}}
```
`parameter-name`
The name of the parameter in the Parameter Store. The parameter name is case-sensitive.
Required.
`version`
An integer that specifies the version of the parameter to use. If you don't specify the exact version, CloudFormation uses the latest version of the parameter whenever you create or update the stack. For more information, see [Working with parameter versions](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-paramstore-versions.html) in the *AWS Systems Manager User Guide*.
Optional.
## Examples
**Topics**
+ [
### Public AMI ID parameter
](#dynamic-references-ssm-public-ami-example)
+ [
### Custom AMI ID parameter
](#dynamic-references-ssm-custom-ami-example)
### Public AMI ID parameter
The following example creates an EC2 instance that references a public AMI parameter. The dynamic reference retrieves the latest Amazon Linux 2023 AMI ID from the public parameter. For more information about public parameters, see [Discovering public parameters in Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/parameter-store-finding-public-parameters.html) in the *AWS Systems Manager User Guide*.
#### JSON
```
{
"Resources": {
"MyInstance": {
"Type": "AWS::EC2::Instance",
"Properties": {
"ImageId": "{{resolve:ssm:/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-6.1-x86_64}}",
"InstanceType": "t2.micro"
}
}
}
}
```
#### YAML
```
Resources:
MyInstance:
Type: AWS::EC2::Instance
Properties:
ImageId: '{{resolve:ssm:/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-6.1-x86_64}}'
InstanceType: t2.micro
```
### Custom AMI ID parameter
The following example creates an EC2 launch template that references a custom AMI ID stored in the Parameter Store. The dynamic reference retrieves the AMI ID from version *`2`* of the `golden-ami` parameter any time an instance is launched from the launch template.
#### JSON
```
{
"Resources": {
"MyLaunchTemplate": {
"Type": "AWS::EC2::LaunchTemplate",
"Properties": {
"LaunchTemplateName": {
"Fn::Sub": "${AWS::StackName}-launch-template"
},
"LaunchTemplateData": {
"ImageId": "{{resolve:ssm:golden-ami:2}}",
"InstanceType": "t2.micro"
}
}
}
}
}
```
#### YAML
```
Resources:
MyLaunchTemplate:
Type: AWS::EC2::LaunchTemplate
Properties:
LaunchTemplateName: !Sub ${AWS::StackName}-launch-template
LaunchTemplateData:
ImageId: '{{resolve:ssm:golden-ami:2}}'
InstanceType: t2.micro
```
# Get a secure string value from Systems Manager Parameter Store
In CloudFormation, you can use sensitive data like passwords or license keys without exposing them directly in your templates by storing the sensitive data as a "secure string" in AWS Systems Manager Parameter Store. For an introduction to Parameter Store, see [AWS Systems Manager Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html) in the *AWS Systems Manager User Guide*.
To use a Parameter Store secure string within your template, you use a `ssm-secure` dynamic reference. CloudFormation never stores the actual secure string value. Instead, it only stores the literal dynamic reference, which contains the plaintext parameter name of the secure string.
During stack creation or updates, CloudFormation accesses the secure string value as needed, without exposing the actual value. Secure strings can only be used for resource properties that support the `ssm-secure` dynamic reference pattern. For more information, see [Resources that support dynamic parameter patterns for secure strings](#template-parameters-dynamic-patterns-resources).
CloudFormation doesn't return the actual parameter value for secure strings in any API calls. It only returns the literal dynamic reference. When comparing changes using change sets, CloudFormation only compares the literal dynamic reference string. It doesn't resolve and compare the actual secure string values.
When using `ssm-secure` dynamic references, there are a few important things to keep in mind:
+ CloudFormation can't access Parameter Store values from other AWS accounts.
+ CloudFormation doesn't support using Systems Manager parameter labels or public parameters in dynamic references.
+ In the `cn-north-1` and `cn-northwest-1` regions, secure strings aren't supported by Systems Manager.
+ Dynamic references for secure values, such as `ssm-secure`, aren't currently supported in custom resources.
+ If CloudFormation needs to roll back a stack update, and the previously specified version of a secure string parameter is no longer available, the rollback operation will fail. In such cases, you have two options:
+ Use `CONTINUE_UPDATE_ROLLBACK` to skip the resource.
+ Recreate the secure string parameter in the Systems Manager Parameter Store, and update it until the parameter version reaches the version used in the template. Then, use `CONTINUE_UPDATE_ROLLBACK` without skipping the resource.
## Resources that support dynamic parameter patterns for secure strings
Resources that support the `ssm-secure` dynamic reference pattern include:
| Resource | Property type | Properties |
| --- | --- | --- |
| [AWS::DirectoryService::MicrosoftAD](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-directoryservice-microsoftad.html) | | `Password` |
| [AWS::DirectoryService::SimpleAD](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-directoryservice-simplead.html) | | `Password` |
| [AWS::ElastiCache::ReplicationGroup](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-elasticache-replicationgroup.html) | | `AuthToken` |
| [AWS::IAM::User](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-iam-user.html) | [LoginProfile](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-properties-iam-user-loginprofile.html) | `Password` |
| [AWS::KinesisFirehose::DeliveryStream](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-kinesisfirehose-deliverystream.html) | [RedshiftDestinationConfiguration](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-properties-kinesisfirehose-deliverystream-redshiftdestinationconfiguration.html) | `Password` |
| [AWS::OpsWorks::App](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-opsworks-app.html) | [Source](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-properties-opsworks-app-source.html) | `Password` |
| [AWS::OpsWorks::Stack](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-opsworks-stack.html) | [CustomCookbooksSource](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-properties-opsworks-stack-source.html) | `Password` |
| [AWS::OpsWorks::Stack](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-opsworks-stack.html) | [RdsDbInstances](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-properties-opsworks-stack-rdsdbinstance.html) | `DbPassword` |
| [AWS::RDS::DBCluster](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-rds-dbcluster.html) | | `MasterUserPassword` |
| [AWS::RDS::DBInstance](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-rds-dbinstance.html) | | `MasterUserPassword` |
| [AWS::Redshift::Cluster](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-redshift-cluster.html) | | `MasterUserPassword` |
## Reference pattern
To reference a secure string value from Systems Manager Parameter Store in your CloudFormation template, use the following `ssm-secure` reference 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+)?}}
```
`parameter-name`
The name of the parameter in the Parameter Store. The parameter name is case-sensitive.
Required.
`version`
An integer that specifies the version of the parameter to use. If you don't specify the exact version, CloudFormation uses the latest version of the parameter whenever you create or update the stack. For more information, see [Working with parameter versions](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-paramstore-versions.html) in the *AWS Systems Manager User Guide*.
Optional.
## Example
The following example uses an `ssm-secure` dynamic reference to set the password for an IAM user to a secure string stored in Parameter Store. As specified, CloudFormation will use version *`10`* of the `IAMUserPassword` parameter for stack and change set operations.
### JSON
```
"MyIAMUser": {
"Type": "AWS::IAM::User",
"Properties": {
"UserName": "MyUserName",
"LoginProfile": {
"Password": "{{resolve:ssm-secure:IAMUserPassword:10}}"
}
}
}
```
### YAML
```
MyIAMUser:
Type: AWS::IAM::User
Properties:
UserName: 'MyUserName'
LoginProfile:
Password: '{{resolve:ssm-secure:IAMUserPassword:10}}'
```
# Get a secret or secret value from Secrets Manager
Secrets Manager is a service that allows you to securely store and manage secrets like database credentials, passwords, and third-party API keys. Using Secrets Manager, you can store and control access to these secrets centrally, so that you can replace hardcoded credentials in your code (including passwords), with an API call to Secrets Manager to retrieve the secret programmatically. For more information, see [What is AWS Secrets Manager?](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html) in the *AWS Secrets Manager User Guide*.
To use entire secrets or secret values that are stored in Secrets Manager within your CloudFormation templates, you use `secretsmanager` dynamic references.
## Best practices
Follow these best practices when using Secrets Manager dynamic references in your CloudFormation templates:
+ **Use versionless references for your CloudFormation templates** – Store credentials in Secrets Manager and use dynamic references without specifying `version-stage` or `version-id` parameters to support proper secret rotation workflows.
+ **Leverage automatic rotation** – Use Secrets Manager's automatic rotation feature with versionless dynamic references for credential management. This ensures your credentials are regularly updated without requiring template changes. For more information, see [Rotate AWS Secrets Manager secrets](https://docs.aws.amazon.com/secretsmanager/latest/userguide/rotating-secrets.html).
+ **Use versioned references sparingly** – Only specify explicit `version-stage` or `version-id` parameters for specific scenarios like testing or rollback situations.
## Considerations
When using `secretsmanager` dynamic references, there are important considerations to keep in mind:
+ CloudFormation doesn't track which version of a secret was used in previous deployments. Plan your secret management strategy carefully before implementing dynamic references. Use versionless references when possible to leverage automatic secret rotation. Monitor and validate resource updates when making changes to dynamic reference configurations, such as when transitioning from unversioned to versioned dynamic references, and vice versa.
+ Updating only the secret value in Secrets Manager doesn't automatically cause CloudFormation to retrieve the new value. CloudFormation retrieves the secret value only during resource creation or updates that modify the resource containing the dynamic reference.
For example, suppose your template includes an [https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-rds-dbinstance.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-rds-dbinstance.html) resource where the `MasterPassword` property is set to a Secrets Manager dynamic reference. After creating a stack from this template, you update the secret's value in Secrets Manager. However, the `MasterPassword` property retains the old password value.
To apply the new secret value, you'll need to modify the `AWS::RDS::DBInstance` resource in your CloudFormation template and perform a stack update.
To avoid this manual process in the future, consider using Secrets Manager to automatically rotate the secret.
+ Dynamic references for secure values, such as `secretsmanager`, aren't currently supported in custom resources.
+ The `secretsmanager` dynamic reference can be used in all resource properties. Using the `secretsmanager` dynamic reference indicates that neither Secrets Manager nor CloudFormation logs should persist any resolved secret value. However, the secret value may show up in the service whose resource it's being used in. Review your usage to avoid leaking secret data.
## Permissions
To specify a secret stored in Secrets Manager, you must have permission to call [https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_GetSecretValue.html](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_GetSecretValue.html) for the secret.
## Reference pattern
To reference Secrets Manager secrets in your CloudFormation template, use the following `secretsmanager` reference pattern.
```
{{resolve:secretsmanager:secret-id:secret-string:json-key:version-stage:version-id}}
```
`secret-id`
The name or ARN of 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.
`secret-string`
The only supported value is `SecretString`. The default is `SecretString`.
`json-key`
The key name of the key-value pair whose value you want to retrieve. If you don't specify a `json-key`, CloudFormation retrieves the entire secret text.
This segment may not include the colon character ( `:`).
`version-stage`
The staging label of the version of the secret to use. Secrets Manager uses staging labels 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 `version-stage` or `version-id`, then the default is the `AWSCURRENT` version.
This segment may not include the colon character ( `:`).
`version-id`
The unique identifier of the version of the secret to use. If you specify `version-id`, then don't specify `version-stage`. If you don't specify either `version-stage` or `version-id`, then the default is the `AWSCURRENT` version.
This segment may not include the colon character ( `:`).
## Examples
**Topics**
+ [
### Retrieving user name and password values from a secret
](#dynamic-references-secretsmanager-examples-user-name-and-password)
+ [
### Retrieving the entire SecretString
](#dynamic-references-secretsmanager-examples-entire-secretstring)
+ [
### Retrieving a value from a specific version of a secret
](#dynamic-references-secretsmanager-examples-specific-version)
+ [
### Retrieving secrets from another AWS account
](#dynamic-references-secretsmanager-examples-secrets-from-another-account)
### Retrieving user name and password values from a secret
The following [https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-rds-dbinstance.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-rds-dbinstance.html) example retrieves the user name and password values stored in the `MySecret` secret. This example shows the recommended pattern for versionless dynamic references, which automatically uses the `AWSCURRENT` version and supports Secrets Manager rotation workflows without requiring template changes.
#### JSON
```
{
"MyRDSInstance": {
"Type": "AWS::RDS::DBInstance",
"Properties": {
"DBName": "MyRDSInstance",
"AllocatedStorage": "20",
"DBInstanceClass": "db.t2.micro",
"Engine": "mysql",
"MasterUsername": "{{resolve:secretsmanager:MySecret:SecretString:username}}",
"MasterUserPassword": "{{resolve:secretsmanager:MySecret:SecretString:password}}"
}
}
}
```
#### YAML
```
MyRDSInstance:
Type: AWS::RDS::DBInstance
Properties:
DBName: MyRDSInstance
AllocatedStorage: '20'
DBInstanceClass: db.t2.micro
Engine: mysql
MasterUsername: '{{resolve:secretsmanager:MySecret:SecretString:username}}'
MasterUserPassword: '{{resolve:secretsmanager:MySecret:SecretString:password}}'
```
### Retrieving the entire SecretString
The following dynamic reference retrieves the `SecretString` for `MySecret`.
```
{{resolve:secretsmanager:MySecret}}
```
Alternatively:
```
{{resolve:secretsmanager:MySecret::::}}
```
### Retrieving a value from a specific version of a secret
The following dynamic reference retrieves the `password` value for the `AWSPREVIOUS` version of `MySecret`.
```
{{resolve:secretsmanager:MySecret:SecretString:password:AWSPREVIOUS}}
```
### Retrieving secrets from another AWS account
The following dynamic reference retrieves the `SecretString` for `MySecret` that's in another AWS account. 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}}
```
The following dynamic reference retrieves the `password` value for `MySecret` that's in another AWS account. 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:SecretString:password}}
```