Get started with ROS templates

A template defines cloud resources and their dependencies. Resource Orchestration Service (ROS) deploys templates as stacks. This guide covers writing, testing, and parameterizing templates.

Overview

After you understand ROS template structure, try writing your first template. Quick start for writing a template.

This guide starts with a simple VPC template, then covers resource dependencies and parameterization:

Write and test a simple template
1. Write a template
2. Test the template
Define multiple resources and their dependencies in a template
Define parameter values and properties in a template

Write a template

Declare resources in the Resources section. Browse supported types and properties in the Resource type index. Quick start for writing a template. The following sample creates 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 the template

Create a stack from the template to verify that it provisions resources as expected.

Log in 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 for the stack from the region drop-down list, for example, China (Hangzhou).
3. On the Stacks page, click Create Stack. In the Specify Template section, click Select an Existing Template.
  Note
  - If you select Create Template or ROS Infrastructure Composer, you are redirected to the corresponding page.
  - If you select Synchronize Template from Code Repository, see Manage stacks by using a code repository.
4. On the Select Template page, click Select an Existing Template in the Specify Template area. Set Template Import Method to Enter Template Content. In the Template Content section, select the ROS tab, paste the YAML template from the Write a template section, and then click Next.
5. On the Configure Parameters page, enter a Stack Name.
6. In the Configure Stack Settings section, configure settings such as Rollback on Failure, Timeout Period, Tags, Resource Group, Stack Policy, Maximum Concurrent Resources, Deletion Protection, RAM Role, Stack Event Callback URLs, and Manual Payment, and then click Next.
7. On the Check and Confirm page, click Preview Template Resources. In the Preview dialog box, review the ROS-validated resource names, types, and properties, and then click OK.
8. On the Check and Confirm page, click Create.
View the stack.
1. On the stack management page, click the Event tab to view the list of events for the resources in the template.
2. Click the Resources tab to view details of the created resources.
  
  Note
  Click a resource ID to open its console and verify the resource configuration.
3. Click the Output tab to view the outputs defined in the Outputs section of the template.

Define multiple resources and their dependencies

A vSwitch must belong to a VPC. Define both resources and their dependency in a single template to provision complex environments in one stack.

Use functions to get the value of a resource's output property.

For example, if a VPC resource is defined in the Resources section, you can use {"Fn::GetAtt": ["VPC", "VpcId"]} to get its VpcId output property.
Use functions to get a resource ID or a parameter value.
For example, if a VPC resource is defined in the Resources section, you can use {"Ref": "VPC"} to reference its resource ID.
Note
- {"Ref": "VPC"} returns the same value as {"Fn::GetAtt": ["VPC", "VpcId"]}, but is more concise.
- Ref and Fn::GetAtt implicitly declare resource dependencies. To explicitly declare dependencies, use the DependsOn attribute.

Add a vSwitch resource.

The following template adds a vSwitch named myvsw in zone cn-beijing-f with CIDR block 192.168.0.0/24, referencing the VPC. The Outputs section includes the vSwitch ID.

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

The Parameters section makes templates reusable. Define parameters to accept different values at stack creation without editing the template.

Define parameters

Hard-coding properties like ZoneId limits a template to one configuration. Define parameters so each stack creation can supply different values. The following table describes the parameters in the sample template.

Parameters in the template

Parameter	Description
`ZoneId`	Sets the vSwitch availability zone.
`VpcCidrBlock`	Sets the VPC CIDR block. Default: `192.168.0.0/16`.
`VSwitchCidrBlock`	Sets the vSwitch CIDR block. Default: `192.168.0.0/24`.

Sample template code

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 create a stack, set parameter values in the ROS console.

ROS infers valid values from resource property associations. For example, because ZoneId maps to the vSwitch ZoneId property, the console shows only zones that support vSwitches.

Dynamically set allowed values

The Parameters section supports properties that customize console behavior. The following table describes the properties in the sample template.

Parameter properties

Property	Description
AllowedValues	Restricts input to a predefined list, shown as a drop-down in the console. Example: `VpcCidrBlock` allows `10.0.0.0/8`, `172.16.0.0/12`, and `192.168.0.0/16`.
Label	Sets a display name for the parameter in the console. Example: `ZoneId` appears as `Availability Zone ID`.

Sample template code

ROSTemplateFormatVersion: '2015-09-01'
Parameters:
  ZoneId:
    Type: String
    Label: Availability 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 create a stack, select parameter values from drop-down lists in the ROS console.

Dynamically present parameters based on associations

Use AssociationProperty and AssociationPropertyMetadata to let the console dynamically query and display allowed values for a parameter.

For example, if a template uses VpcId and vSwitchId as parameters, the console auto-populates drop-down lists:
```
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 create a stack, parameters are dynamically populated in the console.

Group similar parameters

Use the Metadata section to group related parameters for easier configuration in the console.

For example, group ZoneId, VpcCidrBlock, and VSwitchCidrBlock into two groups: Basic Settings (ZoneId) and Resource Settings (VpcCidrBlock, VSwitchCidrBlock):

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 Settings
      - Parameters:
          - VpcCidrBlock
          - VSwitchCidrBlock
        Label:
          default: Resource Settings

When you create a stack, parameters appear grouped in the console.

Overview

Write a template

Test the template

Define multiple resources and their dependencies

Define parameter values and properties

Related topics