Fn::Sub

The intrinsic function Fn::Sub substitutes variables in an input string with values that you specify. In your templates, you can use this function to construct commands or outputs that include values that aren't available until you create or update a stack.

Declaration

The following sections show the function's syntax.

JSON

{ "Fn::Sub" : [ String, { Var1Name: Var1Value, Var2Name: Var2Value } ] }

If you're substituting only template parameters, resource logical IDs, or resource attributes in the String parameter, don't specify a variable map.

{ "Fn::Sub" : String }

YAML

Syntax for the full function name:

Fn::Sub:
  - String
  - Var1Name: Var1Value
    Var2Name: Var2Value

Syntax for the short form:

!Sub
  - String
  - Var1Name: Var1Value
    Var2Name: Var2Value

If you're substituting only template parameters, resource logical IDs, or resource attributes in the String parameter, don't specify a variable map.

Syntax for the full function name:

Fn::Sub: String

Syntax for the short form:

!Sub String

Parameters

String

A string with variables that AWS CloudFormation substitutes with their associated values at runtime. Write variables as ${MyVarName}. Variables can be template parameter names, resource logical IDs, resource attributes, or a variable in a key-value map. If you specify only template parameter names, resource logical IDs, and resource attributes, don't specify a key-value map.

If you specify template parameter names or resource logical IDs, such as ${InstanceTypeParameter}, CloudFormation returns the same values as if you used the Ref intrinsic function. If you specify resource attributes, such as ${MyInstance.PublicIp}, CloudFormation returns the same values as if you used the Fn::GetAtt intrinsic function.

To write a dollar sign and curly braces (${}) literally, add an exclamation point (!) after the open curly brace, such as ${!Literal}. CloudFormation resolves this text as ${Literal}.

VarName

The name of a variable that you included in the String parameter.

VarValue

The value that CloudFormation substitutes for the associated variable name at runtime.

Return value

CloudFormation returns the original string, substituting the values for all the variables.

Examples

The following examples demonstrate how to use the Fn::Sub function.

Fn::Sub with a mapping

The following example uses a mapping to substitute the ${Domain} variable with the resulting value from the Ref function.

JSON

{
    "Name": {
        "Fn::Sub": [
            "www.${Domain}",
            {
                "Domain": {
                    "Ref": "RootDomainName"
                }
            }
        ]
    }
}

YAML

Name: !Sub 
  - 'www.${Domain}'
  - Domain: !Ref RootDomainName

Fn::Sub without a mapping

The following example uses Fn::Sub with the AWS::Region and AWS::AccountId pseudo parameters and the vpc resource logical ID to create an Amazon Resource Name (ARN) for a VPC.

JSON

{ "Fn::Sub": "arn:aws:ec2:${AWS::Region}:${AWS::AccountId}:vpc/${vpc}" }

YAML

!Sub 'arn:aws:ec2:${AWS::Region}:${AWS::AccountId}:vpc/${vpc}'

 

UserData commands

The following example uses Fn::Sub to substitute the AWS::StackName and AWS::Region pseudo parameters for the actual stack name and region at runtime.

JSON

For readability, the JSON example uses the Fn::Join function to separate each command, instead of specifying the entire user data script in a single string value.

"UserData": { "Fn::Base64": { "Fn::Join": ["\n", [
  "#!/bin/bash -xe",
  "yum update -y aws-cfn-bootstrap",
  { "Fn::Sub": "/opt/aws/bin/cfn-init -v --stack ${AWS::StackName} --resource LaunchConfig --configsets wordpress_install --region ${AWS::Region}" },
  { "Fn::Sub": "/opt/aws/bin/cfn-signal -e $? --stack ${AWS::StackName} --resource WebServerGroup --region ${AWS::Region}" }]]
}}

YAML

The YAML example uses a literal block to specify the user data script.

UserData:
  Fn::Base64:
    !Sub |
      #!/bin/bash -xe
      yum update -y aws-cfn-bootstrap
      /opt/aws/bin/cfn-init -v --stack ${AWS::StackName} --resource LaunchConfig --configsets wordpress_install --region ${AWS::Region}
      /opt/aws/bin/cfn-signal -e $? --stack ${AWS::StackName} --resource WebServerGroup --region ${AWS::Region}

Supported functions

For the String parameter, you can't use any functions. You must specify a string value.

For the VarName and VarValue parameters, you can use the following functions:

• Fn::Base64

• Fn::FindInMap

• Fn::GetAtt

• Fn::GetAZs

• Fn::If

• Fn::ImportValue

• Fn::Join

• Fn::Select

• Ref