get started with ROS templates - Resource Orchestration Service

A template serves as the blueprint for your infrastructure and architecture. You can define cloud service resources and their dependency relationships in templates to deploy the resources by using Resource Orchestration Service (ROS). This topic describes how to create and test a template and define resources and their dependency relationships in a template to help you quickly get started with templates.

Background information

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

This topic walks you through the process of how to create and test a simple template. In this example, the template is used to create a virtual private cloud (VPC). This topic also describes how to define advanced configurations such as resources, dependency relationships between the resources, and parameters in a template to apply the template in different deployment scenarios. This topic includes the following sections:

Create and test a template:
1. Create a template
2. Test a template
Define resources and their dependency relationships in a template
Define parameter values and properties in a template

Create a template

To create a template, you must declare the resources that you want to create in the Resources section of the template. You can refer to List of resource types by service to view all resource types that are supported by ROS. Then, you can click a resource type in this documentation to view details of the supported properties and return values. For more information about how to create a template, see Getting started with template creation. The following sample template is 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 you create the template, you can test whether the template can be used to create resources as expected. To test the template, create a stack by using the template.

Log on to the ROS console.
Create a stack.
1. In the left-side navigation pane, click Stacks.
2. In the top navigation bar, select the region where you want to create a stack from the region drop-down list. For example, you can select China (Hangzhou).
3. On the Stacks page, click Create Stack and select Use ROS from the drop-down list.
4. In the Select Template step, select Select an Existing Template in the Specify Template section and set the Template Import Method parameter to Enter Template Content. On the ROS tab of the Template Content section, enter the YAML template that you created in the Create a template section of this topic. Then, click Next.
5. In the Configure Parameters step, specify the Stack Name parameter.
6. In the Configure Stack Settings step, configure the Rollback on Failure, Timeout Period, Tags, Resource Group, Stack Policy, Maximum Concurrent Resources, Deletion Protection, RAM Role, Stack Event Callback URLs, Manual Payment parameters, and click Next.
7. In the Check and Confirm step, click Preview Template Resources. In the Preview dialog box, check the names, types, and properties of template resources that are validated by ROS. Then, click OK.
8. In the Check and Confirm step, click Create.
View the stack.
1. Click the name of the stack to go to the stack management page. Click the Events tab to view the events of each resource in the stack.
2. Click the Resources tab to view the resources that are created.
  Note
  To view more information about a resource, you can click the ID of the resource to go to the relevant console. This way, you can check whether the resource meets your expectations.
3. Click the Outputs tab to view the outputs that are defined in the Outputs section of the template.

Define resources and their dependency relationships in a template

Your deployment scenario may require you to define resources and their dependency relationships in a template. For example, a deployment scenario in which a vSwitch depends on a VPC may require you to create a vSwitch in a specified VPC. In this case, you can define the VPC and vSwitch resources and dependency relationships between the resources in a template. Then, you can use the template to deploy stacks in complex scenarios.

Invoke the Fn::GetAtt function to obtain the output property value of a resource. For more information, see Functions.
For example, if you define the VPC in the Resources section, you can use {"Fn::GetAtt": ["VPC", "VpcId"]} to obtain the value of VpcId.
Invoke the Ref function to reference the ID of a resource or the value of a parameter. For more information, see Functions.
For example, if you define the VPC in the Resources section, you can use {"Ref": "VPC"} to reference the ID of the VPC.
Note
- {"Ref": "VPC"} and {"Fn::GetAtt": ["VPC", "VpcId"]} have the same effect. However, {"Ref": "VPC"} is easier to be configured than {"Fn::GetAtt": ["VPC", "VpcId"]}.
- You can invoke the Ref and Fn::GetAtt functions to implicitly declare the dependency relationships between resources. You can also use the DependsOn property to explicitly declare the dependency relationships between resources. For more information, see DependsOn.

Optimize the template.

The following sample code provides an example on how to optimize a template. In this example, a vSwitch named myvsw is declared. The zone ID of the vSwitch is cn-beijing-f. The CIDR block of the vSwitch is 192.168.0.0/24. The VPC is referenced by the vSwitch. 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. You can define parameter values and properties in the Parameters section of a template to meet your business requirements, such as displaying valid values as selectable options for a parameter and grouping parameters of the same type.

Define resource properties as parameters

You can specify literal values for resource properties in a template. However, each time you use the template in a different scenario, you must change the literal values of the properties in the template. For example, if you set ZoneId to cn-beijing-f in the template, you can use the template to create stacks only in the China (Beijing) region. If you want to create stacks in a different region, you must change the literal value of ZoneId in the template. To improve the reusability of a template, you can add the properties that are frequently used or shared by multiple resources in the Resources section to the Parameters section and define the properties as parameters. This way, you can specify different parameter values to create resources that have different property values each time you use the template. The following table describes the parameters that you can define in a template. The following sample code provides an example on how to define the parameters in the template.

Parameters 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 the sample template to create a stack, you can specify parameter values in the ROS console based on your business requirements.

ROS analyzes the associations between parameters and resource properties in the template to display a set of valid values for each parameter. In this example, the ZoneId parameter in the template is associated with the ZoneId property of the vSwitch. ROS queries the zones in which the vSwitch is supported and displays the zones in the console.

Display valid values as selectable options for a parameter

The Parameters section supports parameter properties. If you define parameter properties in the Parameters section, ROS displays the parameter properties and values in the console. The following table describes the parameter properties that you can define in a template. The following sample code provides an example on how to define the parameter properties in the template.

Parameter properties in the Parameters section

Parameter property	Description
AllowedValues	The valid values of a parameter. The values are shown as selectable options in the ROS console. In this example, the valid values of the VpcCidrBlock parameter are 10.0.0.0/8, 172.16.0.0/12, and 192.168.0.0/16.
Label	The alias of a parameter. The alias of the parameter is displayed in the ROS console. In this example, Zone ID is displayed as the alias of ZoneId in the ROS console.

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 the sample template to create a stack, ROS displays a set of valid values as selectable options in the console.

Display different parameter sets based on the value of a parameter
After you define the AssociationProperty and AssociationPropertyMetadata properties for parameters, ROS displays the values of different parameter sets in the console based on the value chosen for a parameter. For more information, see AssociationProperty and AssociationPropertyMetadata.
For example, if you define the VpcId and vSwitchId parameters in a template and use the template to create an Elastic Compute Service (ECS) instance, ROS displays the values of the parameters in drop-down lists 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 the sample template to create a stack, ROS displays parameter sets in the console based on the value chosen for a parameter.
Group parameters of the same type
You can group parameters in the Metadata section. If you define a large number of parameters in a template, you can group the parameters based on parameter characteristics to facilitate parameter configurations in the ROS console.
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 the sample template to create a stack, ROS displays the Basic Configurations and Resource Configurations sections in the console to allow you to configure parameters by group.

What to do next

Familiarize yourself with the best practices for creating templates. For more information, see Template deployment.
Save a template as your template. For more information, see Create a template.
Share a template. For more information, see Share a template with Alibaba Cloud accounts and Share a template with members in a resource directory.
Estimate resource prices by using a template. For more information, see Estimate resource prices.
Familiarize yourself with the template syntax. For more information, see Template syntax.
Create custom resources by using a template. For more information, see Custom resources.
Nest modules in a template. For more information, see Use a module.