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 whose variables you want to substitute with new values.

  If you specify variables in the ${VarName} format, the variables can be template parameters, pseudo parameters, resource names, resource properties, or variables in a key-value map. If you specify only template parameters, pseudo parameters, resource names, and resource properties, you do not need to specify a key-value map. For more information, see Sample syntax in a template.

  If you specify template parameters, pseudo parameters, or resource names in the ${VarName} format, such as ${MyParameter}, Resource Orchestration Service (ROS) returns the same values as the values that are returned when you use the built-in function Ref. If you specify resource properties in the ${VarName} format, such as ${MyInstance.InstanceId}, ROS returns the same values as the values that are returned when you use the built-in function Fn::GetAtt.

  Note

  If you do not want to substitute a variable, append an exclamation point (!) to the opening brace ({) to use the ${!VarName} format. For example, if you specify ${!Literal}, ROS resolves the text as ${Literal}.

• VarName: the name of the variable that is contained in the string.

• VarValue: the value that ROS substitutes for the associated variable name.

Return value

The string whose variables are substituted with new values.

Sample syntax in a template

If you need to only reference template parameters, pseudo parameters, resource names, and resource attributes, you do not need to use data of the dictionary type to substitute variables. In this case, you can use the ${} format. 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