A template is a declaration of your infrastructure and architecture that make up a stack. You can use Resource Orchestration Service (ROS) templates to declare resources and use the templates to deploy these resources at scale.

Background information

Before you create your first template, we recommend that you familiarize yourself with the structure of ROS templates. For more information about the template structure, see Template structure.

This topic describes how to create and test a template. The template created in this topic can be used to deploy a virtual private cloud (VPC). This topic also describes the relationships between resources and their dependencies, and how to configure template parameters to adapt templates to different usage scenarios.

Create a template

To create a template, you must declare resources in the Resources section. For information about the resource types that are supported by ROS, see List of resource types by service. You can click the name of a resource type to view the properties of the resource type and the values returned by the resource type.

  1. Query the details about resource types based on the deployment scenario.
    1. Visit List of resource types by service to query the details about the resource types that are suitable for your deployment scenario. In this example, the resource type ALIYUN::ECS::VPC is used to create a VPC.
    2. Go to the topic that has the same name as your resource type (ALIYUN::ECS::VPC) to view its properties.
      Resource type topics provide information about resource types in an easy-to-read table.
      • If the value in the Required column is "Yes", you must declare the property in the Properties part of the Resources section. Otherwise, you do not need to declare the property in the Properties part of the Resources section.
      • If the value in the Editable column is "Yes", you can modify the property value in the template. After the modification, you can use the new template to update cloud resources in the stack that is deployed by using the previous template. Otherwise, you cannot modify the property value.
  2. Declare the resources that you want to create in the Resources section. For more information, see Resources.
    In this example, the VPC name that is specified by VpcName and the CIDR block that is specified by CidrBlock are defined in the Resources section. The following snippet provides an example on how to compile the Resources section in a template. 
    "Resources": {
    "VPC": {
      "Type": "ALIYUN::ECS::VPC",
      "Properties": {
        "VpcName": "myvpc",
        "CidrBlock": "192.168.0.0/16"
      }
    }
  }
  3. Define the outputs generated after you use the template to create a stack. For more information, see Outputs.
    In this example, the VPC ID that is specified by VpcId is defined in the Outputs section. The following snippet provides an example on how to compile the Outputs section in a template. 
    "Outputs": {
    "VpcId": {
      "Value": { "Ref": "VPC" }
    },
    "VRouterId": {
      "Value": { "Fn::GetAtt": ["VPC", "VRouterId"] }
    }
  }
  4. Create a complete template.
    For more information, see Template structure.

    The following snippet provides a sample template that can be used to create a VPC.

    {
  "ROSTemplateFormatVersion": "2015-09-01",
  "Resources": {
    "VPC": {
      "Type": "ALIYUN::ECS::VPC",
      "Properties": {
        "VpcName": "myvpc",
        "CidrBlock": "192.168.0.0/16"
      }
    }
  },
  "Outputs": {
    "VpcId": {
      "Value": { "Ref": "VPC" }
    },
    "VRouterId": {
      "Value": { "Fn::GetAtt": ["VPC", "VRouterId"] }
    }
  }
}

Test a template

After a template is created, we recommend that you test whether the template can be used to create resources as expected. To do this, use the template to create a stack.

  1. Log on to the ROS console.
  2. Create a stack.
    1. In the left-side navigation pane, click Stacks.
    2. In the upper-left corner of the page, select a region in which you want to create a stack from the drop-down list. In this example, China (Beijing) is selected.
    3. On the Stacks page, click Create Stack and select Use New Resources (Standard) from the drop-down list.
    4. In the Select Template step, select Select an Existing Template in the Specify Template section and set Template Import Method to Enter Template Content. In the Template Content section, enter the content of the JSON template that you created in the Create a template section on the ROS tab. Then, click Next.
    5. In the Configure Template Parameters step, configure Stack Name and click Next.
    6. In the Configure Stack step, configure the following parameters as needed: Stack Policy, Rollback on Failure, Timeout Period, Deletion Protection, RAM Role, Tags, and Resource Group. Then, click Next.
    7. In the Check and Confirm step, click Preview Template Resources. In the Preview dialog box, check the resource name, resource type, and resource properties in the template that is verified by ROS. Then, click OK.
    8. In the Check and Confirm step, click Create.
  3. View the stack.
    1. Click the name of the stack and go to the stack management page. Then, click the Events tab to view the events of the resources in the stack.
      Events
    2. Click the Resources tab to view the resources that are created.
      Note To view more information about a cloud resource, you can click the ID of the resource to go to the resource console. The resource console provides more information. You can use this information to check whether the resource is created as expected.
      Resources
    3. Click the Outputs tab to view the outputs that are defined in the Outputs section of the template.
      Outputs

Define resources and resource dependencies in a template

Your deployment scenario may require you to define multiple resources and the dependencies between the resources in the template. This section provides an example on how to create a vSwitch inside a VPC. The vSwitch is dependent on the VPC. After the template is created, you can use the template to deploy stacks in complex scenarios.

  1. Obtain the output values of resource properties by using the Fn::GetAtt function.
    For example, if a VPC is defined in the Resources section, you can use the {"Fn::GetAtt": ["VPC", "VpcId"]} function to obtain the value of VpcId.
  2. Obtain the IDs of resources or parameter values by using the Ref function.
    For example, if a VPC is defined in the Resources section, you can use the {"Ref": "VPC"} function to reference the ID of the VPC.
    Note
    • {"Ref": "VPC"} and {"Fn::GetAtt": ["VPC", "VpcId"]} have the same effect. However, {"Ref": "VPC"} is easier than {"Fn::GetAtt": ["VPC", "VpcId"]}.
    • Dependent resources have implicit dependencies that are declared by the Ref and Fn::GetAtt functions. You can use the DependsOn attribute to explicitly declare the dependencies between resources.
  3. Optimize the template.
    The following snippet provides an example on how to optimize a template. In the snippet, a vSwitch named myvsw in the cn-beijing-f zone is added. The CIDR block of the vSwitch is 192.168.0.0/24. And a VPC is referenced. In addition, the vSwitch ID is defined in the Outputs section. 
    {
  "ROSTemplateFormatVersion": "2015-09-01",
  "Resources": {
    "VPC": {
      "Type": "ALIYUN::ECS::VPC",
      "Properties": {
        "VpcName": "myvpc",
        "CidrBlock": "192.168.0.0/16"
      }
    },
    "VSwitch": {
      "Type": "ALIYUN::ECS::VSwitch",
      "Properties": {
        "VpcId": { "Ref": "VPC" },
        "ZoneId": "cn-beijing-f",
        "VSwitchName": "myvsw",
        "CidrBlock": "192.168.0.0/24"
      }
    }
  },
  "Outputs": {
    "VpcId": {
      "Value":  "Fn::GetAtt": ["VPC", "VpcId"] }
    },
    "VRouterId": {
      "Value": { "Fn::GetAtt": ["VPC", "VRouterId"] }
    },
    "VSwitchId": {
      "Value": { "Ref": "VSwitch" }
    }
  }
}

Define parameter values and properties in a template

The Parameters section can improve the flexibility and reusability of a template. If you have specific requirements on parameters in the console, such as dynamically showing parameter values and grouping parameters, you can define parameter values and properties in the template.

  • Define parameters

    You can specify static values for resource properties in a template. However, this method results in templates that need to be modified each time you want to deploy stacks in different scenarios. For example, if you set ZoneId to cn-beijing-f in the template, you can create stacks only in the China (Beijing) region. If you want to create stacks in other regions, you must manually modify the value of ZoneId in the template. To improve the reusability of the template, you can add the parameters that are frequently used or shared by multiple resources to the Parameters section. The Parameters section allows you to use the same template to create resources that have different properties. You only need to specify a parameter value that you require each time. The following table provides some sample parameters that are defined in the template. The following snippet provides a sample template.

    • Parameters defined in the template
      Parameter Description
      ZoneId This parameter is referenced by the ZoneId property of the vSwitch.
      VpcCidrBlock This parameter is referenced by the CidrBlock property of the VPC. Default value: 192.168.0.0/16.
      VSwitchCidrBlock This parameter is referenced by the CidrBlock property of the vSwitch. Default value: 192.168.0.0/24.
    • Sample code of the template
      {
  "ROSTemplateFormatVersion": "2015-09-01",
  "Parameters": {
    "ZoneId": {
      "Type": "String"
    },
    "VpcCidrBlock": {
      "Type": "String",
      "Default": "192.168.0.0/16"
    },
    "VSwitchCidrBlock": {
      "Type": "String",
      "Default": "192.168.0.0/24"
    }
  },
  "Resources": {
    "VPC": {
      "Type": "ALIYUN::ECS::VPC",
      "Properties": {
        "VpcName": "myvpc",
        "CidrBlock": { "Ref": "VpcCidrBlock" }
      }
    },
    "VSwitch": {
      "Type": "ALIYUN::ECS::VSwitch",
      "Properties": {
        "VpcId": { "Ref": "VPC" },
        "ZoneId": { "Ref": "ZoneId" },
        "VSwitchName": "myvsw",
        "CidrBlock": { "Ref": "VSwitchCidrBlock" }
      }
    }
  },
  "Outputs": {
    "VpcId": {
      "Value": { "Ref": "VPC" }
    },
    "VRouterId": {
      "Value": { "Fn::GetAtt": ["VPC", "VRouterId"] }
    },
    "VSwitchId": {
      "Value": { "Ref": "VSwitch" }
    }
  }
}

      When you use this sample template to create a stack, specify parameter values in the ROS console based on your business requirements.

      1

      ROS analyzes the association between parameters and resource properties in the template to obtain the value range of parameters. For example, if the ZoneId parameter in the template is associated with the ZoneId property of the vSwitch, ROS obtains the zones in which the vSwitch is supported and shows the zones in the console.

      Zone ID
  • Dynamically configure parameter values

    The Parameters section supports multiple properties. After you define parameter properties in the Parameters section, ROS dynamically displays the parameter properties and values in the console. The following table provides some sample properties that are defined in the template. The following snippet provides a sample template.

    • Properties defined in the Parameters section
      Property Description
      AllowedValues Specifies the values of a parameter. The values are shown as selectable options in the ROS console. For example, the values of the VpcCidrBlock parameter are 10.0.0.0/8, 172.16.0.0/12, and 192.168.0.0/16.
      Label Specifies the alias of a parameter. The alias is displayed in the ROS console. For example, if you set Label to Zone ID, ROS displays "Zone ID" as the alias of the ZoneId parameter.
    • Sample code of the template
      {
  "ROSTemplateFormatVersion": "2015-09-01",
  "Parameters": {
    "ZoneId": {
      "Type": "String",
      "Label": "Zone ID"
    },
    "VpcCidrBlock": {
      "Type": "String",
      "Label": "VPC CIDR block",
      "Default": "192.168.0.0/16",
      "AllowedValues": ["10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16"]
    },
    "VSwitchCidrBlock": {
      "Type": "String",
      "Label": "vSwitch CIDR block",
      "Default": "192.168.0.0/24"
    }
  }
}
      When you use this sample template to create a stack, ROS provides a list of values as selectable options in the console. 3
  • Dynamically show parameters based on parameter association

    After you define the AssociationProperty and AssociationPropertyMetadata properties of a parameter, ROS dynamically shows the values of the parameter in the console. For more information, see AssociationProperty and AssociationPropertyMetadata.

    For example, if you want to use the template to create an Elastic Compute Service (ECS) instance, the VpcId and vSwitchId parameters need to be passed in. ROS automatically shows the values of the two parameters in the console. Sample code of the template: 

    {
  "ROSTemplateFormatVersion": "2015-09-01",
  "Parameters": {
    "VpcId": {
      "Type": "String",
      "AssociationProperty": "ALIYUN::ECS::VPC::VPCId"
    },
    "ZoneId": {
      "Type": "String",
      "AssociationProperty": "ALIYUN::ECS::ZoneId"
    },
    "VSwitchId": {
      "Type": "String",
      "AssociationProperty": "ALIYUN::ECS::VSwitch::VSwitchId",
      "AssociationPropertyMetadata": {
        "ZoneId": "${ZoneId}",
        "VpcId": "${VpcId}"
      }
    }
  }
}

    When you use this sample template to create a stack, ROS dynamically shows parameters in the console.

    4
  • Centrally configure parameters of the same type

    The Metadata section allows you to group parameters. If many parameters are defined in the template, you can group the parameters based on parameter characteristics to facilitate parameter configurations.

    For example, you can group ZoneId into Basic Configurations, and group VpcCidrBlock and VSwitchCidrBlock into Resource Configurations. You can define Basic Configurations and Resource Configurations in the ParameterGroups part of the Metadata section. Sample code of the template: 

    {
  "ROSTemplateFormatVersion": "2015-09-01",
  "Parameters": {
    "ZoneId": {
      "Type": "String"
    },
    "VpcCidrBlock": {
      "Type": "String",
      "Default": "192.168.0.0/16"
    },
    "VSwitchCidrBlock": {
      "Type": "String",
      "Default": "192.168.0.0/24"
    }
  },
  "Metadata": {
    "ALIYUN::ROS::Interface": {
      "ParameterGroups": [
        {
          "Parameters": ["ZoneId"],
          "Label": {
            "default": "Basic Configurations"
          }
        },
        {
          "Parameters": ["VpcCidrBlock", "VSwitchCidrBlock"],
          "Label": {
            "default": "Resource Configurations"
          }
        }
      ]
    }
  }
}

    When you use this sample template to create a stack, ROS provides two sections in the console. The Basic Configurations section contains the ZoneId parameter, and the Resource Configurations section contains the VpcCidrBlock and VSwitchCidrBlock parameters.

    5