Getting started with templates - Resource Orchestration Service

Templates are used to create stacks and serve as the blueprints for underlying infrastructures and architectures. You can declare the resources of cloud services in Resource Orchestration Service (ROS) templates and use the templates to deploy the resources.

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 helps you walk through the process about how to create and test a template. In this example, a simple template that is used to create a virtual private cloud (VPC) is used. This topic also describes how to specify advanced configurations such as resources, resource associations, and parameters in a template to adapt the template to different scenarios. This topic includes the following sections:

Create and test a template:
1. Create a template
2. Test a template
Define resources and associate the resources 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. For more information about the resource types that are supported by ROS, see List of resource types by service. You can click a resource type in the documentation to view the properties and the return values of the resource type.

Query the details of a resource type based on your deployment scenario.
1. Refer to the List of resource types by service documentation to query the resource type that is suitable for your deployment scenario. In this example, the ALIYUN::ECS::VPC resource type that is used to create a VPC is queried.
2. Click the ALIYUN::ECS::VPC resource type to view the details of resource properties.
  The documentation for each resource type provides information about properties of a resource in the table format and contains the "Type", "Required", "Editable", and "Constraints" columns.
  - 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 in a new template after the property is specified for a cloud resource in a stack template. Then, you can use the new template to update the stack and the resource. Otherwise, you cannot modify the property.
In the Resources section, declare the resources that you want to create.
The following sample code provides an example on how to declare resources in the Resources section. In this example, the VPC name that is specified by VpcName and the CIDR block that is specified by CidrBlock are declared.
```
Resources:
  VPC:
    Type: ALIYUN::ECS::VPC
    Properties:
      VpcName: myvpc
      CidrBlock: 192.168.0.0/16
```
In the Outputs section, define the outputs that you want to obtain after you use the template to create a stack.
The following sample code provides an example on how to define outputs. In this example, the VPC ID that is specified by VpcId is defined.
```
Outputs:
  VpcId:
    Value:
      Ref: VPC
  VRouterId:
    Value:
      Fn::GetAtt:
        - VPC
        - VRouterId
```

Follow the template structure to create a complete template.

For more information, see Template structure.

The following sample code provides an example of a template that 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 upper-left corner of the page, select the 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 Existing Resources (Resource Import) 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, click the ROS tab and enter the content of the JSON template that you created in the Create a template section. Then, click Next.
5. In the Configure Template Parameters step, specify Stack Name and click Next.
6. On the Compliance Precheck page, complete the compliance precheck and click Next.
  Note
  The compliance precheck feature is available only for specific resources. For more information, see Compliance precheck of ROS.
  1. In the Evaluate Rules section, add a compliance rule.
    You can add compliance rules based on the cloud resources in the ROS template.
  2. In the Continuous Monitoring section, specify whether to enable continuous detection.
    After you enable continuous detection, ROS continuously detects the cloud resources within your Alibaba Cloud account based on the compliance rules that you add. You can view the compliance precheck results in the Cloud Config console. This allows you to detect and handle non-compliant resources at the earliest opportunity.
  3. Click Evaluate.
    You can modify the template content based on the provided suggestions to remediate invalid resources and ensure the compliance of the resources.
7. In the Configure Stack step, configure the following parameters: Stack Policy, Rollback on Failure, Timeout Period, Deletion Protection, RAM Role, Tags, and Resource Group. Then, click Next.
8. 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 and click OK.
9. 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. Then, click the Events tab to view the events of each resource in the stack.
2. Click the Resources tab to view the details of the resources created in the stack.
  Note
  To view more information about a resource, you can click the ID of the resource to go to the relevant console and check whether the resource is created as expected.
3. Click the Outputs tab to view the outputs that you defined in the Outputs section of the template.

Define resources and associate the resources in a template

Your deployment scenario may require you to define resources and associate the resources in a template. For example, your deployment scenario may require you to create a vSwitch in a specified VPC. In this case, you can define the VPC resource and the vSwitch resource and associate 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 value of a property from a resource in the template.
For example, if you define the VPC resource in the Resources section, you can use {"Fn::GetAtt": ["VPC", "VpcId"]} to obtain the value of VpcId.
Use the Ref function to reference the ID of a resource or the value of a parameter.
For example, if you define the VPC resource 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"]}.
- Associated resources have implicit associations that are declared by using the Ref and Fn::GetAtt functions. You can use the DependsOn property to explicitly declare the associations 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, and the CIDR block of the vSwitch is 192.168.0.0/24. A 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. If you have specific requirements on parameters in the console, such as displaying valid values as selectable options for a parameter and grouping parameters of the same type, you can define parameter values and properties in the Parameters section of a template.

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 resource.
`VpcCidrBlock`	This parameter is referenced by the CidrBlock property of the VPC resource. Default value: 192.168.0.0/16.
`VSwitchCidrBlock`	This parameter is referenced by the CidrBlock property of the vSwitch resource. 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 the selectable values of each parameter. In this example, the ZoneId parameter in the template is associated with the ZoneId property of the vSwitch resource. 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 instead of the parameter is displayed in the ROS console. In this example, Zone ID instead of ZoneId is displayed 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 list of 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 of a specified 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 templates. For more information, see Template deployment.