how to use JSON/YAML template syntax to write and validate templates-Compute Nest(Compute Nest)-阿里云帮助中心

When creating a service in Compute Nest, a service provider must provide a template. You must first write a template and then paste its content into the template editor in the Compute Nest console or upload the template file. This topic uses the creation of a Virtual Private Cloud (VPC) as an example to describe how to write a template in JSON or YAML and validate it in the Resource Orchestration Service (ROS) console.

Background information

Templates in Compute Nest are essentially Resource Orchestration Service (ROS) templates. You can write a stack template that follows the specifications defined by ROS. In the template, you can define the required cloud resources, such as ECS instances and ApsaraDB RDS instances, and the dependencies between them. The ROS orchestration engine automatically creates and configures all resources based on your template, enabling automated deployment and operations. Resource Orchestration Service is an Alibaba Cloud service that simplifies cloud resource management. For more information, see What is Resource Orchestration Service?.

Write a template

ROS supports templates written in JSON/YAML and Terraform syntax. You can write a template by modifying a sample or by creating one from scratch.

For common scenarios, ROS provides template samples. You can select and modify a suitable reference template from the Template Samples page in the ROS console. Templates in the ISV Software Deployment category under Scenarios are commonly used for Compute Nest scenarios. The modification steps for these samples are provided in the template descriptions.

If you use a sample template and only need to make simple changes, we recommend that you skip to the Validate the template in the ROS console section. You can select and modify the sample template when creating the stack.
For complex scenarios, you can use any text editor to write your template from scratch.

For JSON/YAML templates, we recommend that you install the Alibaba Cloud Toolkit plug-in for VSCode or IntelliJ IDEA. This provides syntax auto-completion while you write. For download and usage instructions, see Manage templates and stacks by using Alibaba Cloud Toolkit (Visual Studio Code).
If you have complex Terraform projects with multiple files, we recommend converting your Terraform template into the ROS template format. This allows you to package your entire Terraform configuration into a single file. When you paste this ROS-formatted template into the Compute Nest console, the system automatically recognizes the content as a Terraform deployment. This simplifies the process, eliminating the need to upload multiple Terraform files. To convert a Terraform template to the ROS format, follow these steps:
- Install ROS Template Transformer. We recommend using pip. For more information about other installation methods, see Install the template converter.
```
pip install alibabacloud-ros-tran
```
- Place all your Terraform files in a single directory. Run the following command to convert the Terraform template to a ROS template. Replace {terraform_path} with the path to the parent directory of your Terraform files.
```
rostran transform  {terraform_path} -S terraform --force --compatible --target-format yaml    
```
- Paste the ROS template generated from the previous step into the Compute Nest console. Select ROS as the deployment method. The system then automatically recognizes it as a Terraform template and sets the deployment method to Terraform.

The following YAML template shows how to create an ECS instance:

ROSTemplateFormatVersion: '2015-09-01'
# Parameters
Parameters:
  PayType:
    Type: String
    Label:
      en: ECS instance charge type
    Default: PostPaid
    AllowedValues:
      - PostPaid
      - PrePaid
    AssociationProperty: ChargeType
    AssociationPropertyMetadata:
      LocaleKey: InstanceChargeType
  PayPeriodUnit:
    Type: String
    Label:
      en: Pay period unit
    Default: Month
    AllowedValues:
      - Month
      - Year
    AssociationProperty: PayPeriodUnit
    AssociationPropertyMetadata:
      Visible:
        Condition:
          Fn::Not:
            Fn::Equals:
              - ${PayType}
              - PostPaid
  PayPeriod:
    Type: Number
    Description:
      en: When the subscription duration is Month, the value of Period ranges from 1 to 9, 12, 24, 36, 48, or 60. <br><b><font color='red'> This parameter is valid only when the billing method for the ECS instance is PrePaid. </b></font>
    Label:
      en: Period
    Default: 1
    AllowedValues:
      - 1
      - 2
      - 3
      - 4
      - 5
      - 6
      - 7
      - 8
      - 9
    AssociationProperty: PayPeriod
    AssociationPropertyMetadata:
      Visible:
        Condition:
          Fn::Not:
            Fn::Equals:
              - ${PayType}
              - PostPaid
  EcsInstanceType:
    Type: String
    Label:
      en: Instance type
    AssociationProperty: ALIYUN::ECS::Instance::InstanceType
    AssociationPropertyMetadata:
      ZoneId: ${ZoneId}
      InstanceChargeType: ${InstanceChargeType}
  InstancePassword:
    NoEcho: true
    Type: String
    Description:
      en: The password for logging on to the server. The password must be 8 to 30 characters in length and contain at least three of the following character types: uppercase letters, lowercase letters, digits, and special characters, such as ()`~!@#$%^&*_-+=|{}[]:;<>,.?/.
    Label:
      en: Instance password
    ConstraintDescription:
      en: The password must be 8 to 30 characters in length and contain at least three of the following character types: uppercase letters, lowercase letters, digits, and special characters, such as ()`~!@#$%^&*_-+=|{}[]:;<>,.?/.
    AssociationProperty: ALIYUN::ECS::Instance::Password
    AllowedPattern: '^[a-zA-Z0-9-\(\)\`\~\!\@\#\$\%\^\&\*\_\-\+\=\|\{\}\[\]\:\;\<\>\,\.\?\/]*$'
    MinLength: 8
    MaxLength: 30
  ZoneId:
    Type: String
    AssociationProperty: ALIYUN::ECS::Instance::ZoneId
    Label:
      en: vSwitch availability zone
  VpcId:
    AssociationProperty: ALIYUN::ECS::VPC::VPCId
    Type: String
    Description:
      en: The ID of the VPC where you want to deploy the resources. The ID usually starts with `vpc-`.
    Label:
      en: VPC ID
  VSwitchId:
    AssociationProperty: ALIYUN::ECS::VSwitch::VSwitchId
    AssociationPropertyMetadata:
      VpcId: ${VpcId}
      ZoneId: ${ZoneId}
    Type: String
    Description:
      en: The ID of the vSwitch in the specified VPC and availability zone.
    Label:
      en: vSwitch ID
# Resources
Resources:
  EcsSecurityGroup:
    Type: ALIYUN::ECS::SecurityGroup
    Properties:
      SecurityGroupName:
        Ref: ALIYUN::StackName
      VpcId:
        Ref: VpcId
      # Ingress rule for the security group
      SecurityGroupIngress:
        - PortRange: 80/80
          Priority: 1
          SourceCidrIp: 0.0.0.0/0
          IpProtocol: tcp
          NicType: internet
  EcsInstanceGroup:
    Type: ALIYUN::ECS::InstanceGroup
    Properties:
      # Instance name
      InstanceName:
        Fn::Join:
          - '-'
          - - Ref: ALIYUN::StackName
            - '[1,4]'
      IoOptimized: optimized
      # Billing method
      InstanceChargeType:
        Ref: PayType
      PeriodUnit:
        Ref: PayPeriodUnit
      Period:
        Ref: PayPeriod
      # Network configuration
      VpcId:
        Ref: VpcId
      ZoneId:
        Ref: ZoneId
      VSwitchId:
        Ref: VSwitchId
      SecurityGroupId:
        Ref: EcsSecurityGroup
      # Disk type and size
      SystemDiskCategory: cloud_essd
      SystemDiskSize: 200
      MaxAmount: 1
      # Image
      ImageId: centos_7
      # Instance type
      InstanceType:
        Ref: EcsInstanceType
      Password:
        Ref: InstancePassword
      # Enable public IP
      AllocatePublicIP: true
      # Public bandwidth
      InternetMaxBandwidthOut: 1
  ECSRunCommand:
    Type: ALIYUN::ECS::RunCommand
    Properties:
      InstanceIds:
        Fn::GetAtt:
          - EcsInstanceGroup
          - InstanceIds
      Type: RunShellScript
      Sync: true
      Timeout: 3600
      CommandContent: |-
        #!/bin/bash

# Outputs
Outputs:
  # Display the public IP address as an HTTP endpoint in the console
  Endpoint:
    Description:
      en: Public IP addresses
    Value:
      Fn::Sub:
        - http://${ServerAddress}
        - ServerAddress:
            Fn::Select:
              - 0
              - Fn::GetAtt:
                 - EcsInstanceGroup
                 - PublicIps
# Metadata
Metadata:
  ALIYUN::ROS::Interface:
    # Group information
    ParameterGroups:
      - Parameters:
          - PayType
          - PayPeriodUnit
          - PayPeriod
        Label:
          default:
            en: Paytype configuration
      - Parameters:
          - EcsInstanceType
          - InstancePassword
        Label:
          default:
            en: ECS instance configuration
      - Parameters:
          - ZoneId
          - VpcId
          - VSwitchId
        Label:
          default:
            en: Choose existing infrastructure

A template has four main sections: Parameters, Resources, Outputs, and Metadata.

Parameters

The Parameters section defines the parameters that users configure when creating a service instance. The following table describes the parameters in this example.

Parameter	Description
PayType	The billing method for the instance.
PayPeriodUnit	The unit of the subscription duration.
PayPeriod	The subscription duration.
EcsInstanceType	The instance type of the ECS instance.
InstancePassword	The password of the ECS instance.
ZoneId	The availability zone for the vSwitch.
VpcId	The ID of the VPC.
VSwitchId	The ID of the vSwitch.

Resources

The Resources section defines the resources to create, including the Type and Properties of each resource. The following table describes the resources defined in this example.

Resource type	Description
ALIYUN::ECS::SecurityGroup	Creates an ECS security group.
ALIYUN::ECS::InstanceGroup	Creates an ECS instance.
ALIYUN::ECS::RunCommand	Runs a shell script on the ECS instance.

Note

Refer to the Resource type index for the syntax, properties, and return values (outputs) of each Alibaba Cloud resource type. This information helps you declare specific resource requirements in your templates.

Outputs

The Outputs section defines the information returned after service creation. In this example, the output is an Endpoint (http://PublicIp). After the resources are created, users can use this address to access the service.

Metadata

The Metadata section lets you group parameters defined in the Parameters section and hide custom parameters. You can see the result on the Configure Parameters page in the ROS console. The following table describes the parameter groups in this example.

Group name	Parameter
Paytype configuration	PayType
	PayPeriodUnit
	PayPeriod
ECS instance configuration	EcsInstanceType
ECS instance configuration	InstancePassword
Choose existing infrastructure	ZoneId
	VpcId
	VSwitchId

You can also use advanced features, such as Mappings and Conditions. For more information, see Template structure.

You can also use Terraform to create a template. For more information, see Create a Terraform template.

Validate the template in the ROS console

After you write the template, you can validate it by creating a stack in the ROS console.

Log on to the ROS console.
In the navigation pane on the left, click Stacks.
In the upper-left corner of the page, click Create Stack.
On the Create Stack page, configure the required parameters.
1. In the Specify Template section, select Select an Existing Template and paste your template into the content editor. Alternatively, select Use a Sample Template and modify it.
2. Click Next. On the Configure Parameters page, verify the parameters. Optionally, click Preview Template Resources to check the resource settings.
3. Optional: Click Next. On the Compliance Precheck (Optional) page, configure the parameters.
4. Optional: Click Next. On the Check and Confirm (Optional) page, confirm your configurations.
5. Click Create.
Note
The Configure Stack (Optional) and Check and Confirm (Optional) steps are optional and can be skipped.

If the stack is created successfully, your template is considered valid. If stack creation fails, view the error message and modify your template accordingly.