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
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 and test a simple template.
- Define resources and resource dependencies in a template
- Define parameter values and properties in a template
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.
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.
- Log on to the ROS console.
- Create a stack.
- In the left-side navigation pane, click Stacks.
- 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.
- On the Stacks page, click Create Stack and select Use New Resources (Standard) from the drop-down list.
- 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.
- In the Configure Template Parameters step, configure Stack Name and click Next.
- 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.
- 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.
- In the Check and Confirm step, click Create.
- View the stack.
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.
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.
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.
- Parameters defined in the template
- 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.
- Properties defined in the Parameters section
- 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.
- 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.