All Products
Search

This Product

    Resource Orchestration Service:Get started with ROS templates

    Document Center

    Resource Orchestration Service:Get started with ROS templates

    Last Updated:Jan 17, 2024

    Templates serve as the blueprints for your infrastructure and architecture. You can define cloud service resources and their associations 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 associations 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 about the template structure, see Template structure.

    This topic walks you through the process about 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, resource associations, and parameters in a template to apply the template in different scenarios. This topic includes the following sections:

    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 this documentation to view the properties and the return values of the resource type.

    1. Query the details of a resource type based on your deployment scenario.

      1. Refer to List of resource types by service 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 go to the resource type documentation and view the details of resource properties.

        The documentation of a resource type provides information about each property 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.

    2. 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

    3. 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

    4. Create a template by following the template structure.

      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.

    1. Log on to the ROS console.

    2. 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.

    3. 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.

        Events

      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 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 associations in a template

    Your deployment scenario may require you to define resources and resource associations 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 the resource associations in a template. Then, you can use the template to deploy stacks in complex scenarios.

    1. 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.

    2. Invoke 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"]}.

      • You can invoke the Ref and Fn::GetAtt functions to implicitly declare the associations between resources. You can also use the DependsOn property to explicitly declare the associations between resources. For more information, see DependsOn.

    3. 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. 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. 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 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.

        1

        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 resource. ROS queries the zones in which the vSwitch is supported and displays the zones in the console.

        Zone ID

    • 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.

        3

    • 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.

      4

    • 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.

      5

    What to do next