Resource Orchestration Service:Fn::Sub

Declaration

• JSON

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

• 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"}]

Parameters

• String: the string that contains the variables to substitute.

  Variables use the ${VarName} format and can reference template parameters, pseudo parameters, resource names, resource properties, or key-value map entries. If you reference only template parameters, pseudo parameters, resource names, and resource properties, the key-value map is optional. For more information, see Sample syntax in a template.

  When you reference template parameters, pseudo parameters, or resource names such as ${MyParameter}, Resource Orchestration Service (ROS) resolves them the same way as the Ref function. When you reference resource properties such as ${MyInstance.InstanceId}, ROS resolves them the same way as the Fn::GetAtt function.

  Note

  To prevent a variable from being substituted, add an exclamation point (!) after the opening brace, as in ${!VarName}. For example, ${!Literal} resolves to the literal text ${Literal}.

• VarName: the name of a variable in the string.

• VarValue: the value that replaces the associated variable.

Return value

The string with all variables replaced by their corresponding values.

Sample syntax in a template

When you reference only template parameters, pseudo parameters, resource names, or resource attributes, you can use the ${} format directly without a key-value map. For more information, see Pseudo parameters.

• Return the value of a referenced parameter:

  YAML

  Fn::Sub: ${String}

  JSON

  {"Fn::Sub": "${String}"}

• Return the value of a referenced string:

  YAML

  Fn::Sub: String

  JSON

  {"Fn::Sub": "String"}

Sample code:

ROSTemplateFormatVersion: '2015-09-01'
Outputs:
  StackId1:
    Value:
      Fn::Sub: ${ALIYUN::StackId}
  StackId2:
    Value:
      Fn::Sub: ALIYUN::StackId

{
  "ROSTemplateFormatVersion": "2015-09-01",
  "Outputs": {
    "StackId1": {
      "Value": {
        "Fn::Sub": "${ALIYUN::StackId}"
      }
    },
    "StackId2": {
      "Value": {
        "Fn::Sub": "ALIYUN::StackId"
      }
    }
  }
}

The following result is returned:

StackId1: 0f848ecd-c6fb-47aa-add5-910799c2****
StackId2: ALIYUN::StackId

Sample template

ROSTemplateFormatVersion: '2015-09-01'
Parameters:
  VpcName:
    Type: String
    Default: vpc
Resources:
  Vpc:
    Type: ALIYUN::ECS::VPC
    Properties:
      VpcName:
        Ref: VpcName
      CidrBlock: 10.0.XX.XX
Outputs:
  Pseudo:
    Value:
      !Sub  
        - 'Var1: ${Var1}, Var2: ${Var2}, StackName: ${ALIYUN::StackName}, Region: ${ALIYUN::Region}'
        - Var1: Var1Value
          Var2: Var2Value       
  VpcId:
    Value:
      !Sub 'Return value of the resource: ${Vpc.VpcId}. Resource ID: ${Vpc}'

{
 "ROSTemplateFormatVersion": "2015-09-01",
 "Parameters": {
 "VpcName": {
 "Type": "String",
 "Default": "vpc"
 }
 },
 "Resources": {
 "Vpc": {
 "Type": "ALIYUN::ECS::VPC",
 "Properties": {
 "VpcName": {
 "Ref": "VpcName"
 },
 "CidrBlock": "10.0.XX.XX"
 }
 }
 },
 "Outputs": {
 "Pseudo": {
 "Value": {
 "Fn::Sub": [
 "Var1: ${Var1}, Var2: ${Var2}, StackName: ${ALIYUN::StackName}, Region: ${ALIYUN::Region}",
 {
 "Var1": "Var1Value",
 "Var2": "Var2Value"
 }
 ]
 }
 },
 "VpcId": {
 "Value": {
 "Fn::Sub": "Return value of the resource: ${Vpc.VpcId}. Resource ID: ${Vpc}"
 }
 }
 }
}

The following result is returned:

Var1: Var1Value, Var2: Var2Value, StackName: SubTest, Region: cn-hangzhou
Return value of the resource: vpc-bp11eu7avmtvr37hl****. Resource ID: vpc-bp11eu7avmtvr37hl****

Supported functions

Fn::Indent