如何使用JSON/YAML模板文法來編寫模板並驗證模板 - Compute Nest

在服務商建立計算巢服務的過程中，需要錄入模板。服務商需要先通過完成模板編寫，再將模板複製到計算巢控制台的模板框中或將模板檔案上傳完成錄入。本文以建立VPC為例，介紹如何使用JSON/YAML模板文法來編寫模板並在ROS控制台驗證模板。

背景資訊

計算巢中的模板本質上是ROS模板。您可以遵循ROS定義的模板規範編寫資源棧模板，在模板中定義所需的雲端運算資源（例如：ECS執行個體、RDS資料庫執行個體）、資源間的依賴關係等。ROS的編排引擎將根據模板自動完成所有資源的建立和配置，實現自動化部署及營運。Resource Orchestration Service服務是阿里雲提供的一項簡化雲端運算資源管理的服務。更多資訊，請參見什麼是Resource Orchestration Service服務。

模板編寫

ROS支援JSON/YAML和Terraform兩種模板文法。編寫模板時可以基於模板樣本進行修改，也可以直接編寫模板。

針對常見的情境，ROS提供了模板樣本，您可以在ROS控制台的模板樣本中選擇適用的參考模板進行修改。其中應用情境為ISV軟件部署類別的模板為計算巢情境常用模板，在模板描述中給出了基於該樣本的修改步驟。

如果您採用了模板樣本且改動簡單，我們建議您直接進入到在ROS控制台驗證模板的步驟，在建立資源棧的過程中選擇模板樣本並修改。
針對複雜的情境，需要您自己編寫模板時，您可以使用任何文本編輯工具來編寫模板。
針對已有Terrafrom模板檔案，且Terraform模板檔案較複雜的情況，推薦將Terraform模板轉化為ROS格式的模板，在控制台一鍵粘貼ROS格式的模板後會自動轉換為Terraform 模板。此種方式減少了上傳多個Terraform檔案的複雜度。將Terraform模板轉化為ROS格式的模板個方式如下：
- 安裝阿里雲ROS模板轉換工具（ROS Template Transformer），建議通過pip 安裝，其他安裝方式參考：安裝模板轉換工具
```
pip install alibabacloud-ros-tran
```
- 運行將Terraform 模板轉為ROS模板的命令，將所有Terraform檔案放到一個檔案路徑下，然後通過以下命令轉換為ROS模板。其中{terraform_path}需要替換為Terraform檔案的父路徑。
```
rostran transform  {terraform_path} -S terraform --force --compatible --target-format yaml    
```
- 將上述步驟產生的ROS模板粘貼到計算巢控制台，部署方式選擇ROS, 即可自動識別為Terraform模板，並設定部署方式為Terraform。

本文以建立ECS的YAML模板為例，介紹建立模板的操作：

ROSTemplateFormatVersion: '2015-09-01'
# 參數配置
Parameters:
  PayType:
    Type: String
    Label:
      en: ECS Instance Charge Type
      zh-cn: 付費類型
    Default: PostPaid
    AllowedValues:
      - PostPaid
      - PrePaid
    AssociationProperty: ChargeType
    AssociationPropertyMetadata:
      LocaleKey: InstanceChargeType
  PayPeriodUnit:
    Type: String
    Label:
      en: Pay Period Unit
      zh-cn: 購買資源時間長度周期
    Default: Month
    AllowedValues:
      - Month
      - Year
    AssociationProperty: PayPeriodUnit
    AssociationPropertyMetadata:
      Visible:
        Condition:
          Fn::Not:
            Fn::Equals:
              - ${PayType}
              - PostPaid
  PayPeriod:
    Type: Number
    Description:
      en: When the resource purchase duration is Month, the value of Period ranges from 1 to 9, 12, 24, 36, 48, or 60. <br><b><font color='red'> When ECS instance types are PrePaid valid </b></font>
      zh-cn: 當購買資源時間長度為Month時，Period取值：1~9 <br><b><font color='red'>當ECS執行個體類型為PrePaid有效</b></font>
    Label:
      en: Period
      zh-cn: 購買資源時間長度
    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
      zh-cn: 執行個體類型
    AssociationProperty: ALIYUN::ECS::Instance::InstanceType
    AssociationPropertyMetadata:
      ZoneId: ${ZoneId}
      InstanceChargeType: ${InstanceChargeType}
  InstancePassword:
    NoEcho: true
    Type: String
    Description:
      en: Server login password, Length 8-30, must contain three(Capital letters, lowercase letters, numbers, ()`~!@#$%^&*_-+=|{}[]:;<>,.?/ Special symbol in)
      zh-cn: 伺服器登入密碼,長度8-30，必須包含三項（大寫字母、小寫字母、數字、 ()`~!@#$%^&*_-+=|{}[]:;<>,.?/ 中的特殊符號）
    Label:
      en: Instance Password
      zh-cn: 執行個體密碼
    ConstraintDescription:
      en: Length 8-30, must contain three(Capital letters, lowercase letters, numbers, ()`~!@#$%^&*_-+=|{}[]:;<>,.?/ Special symbol in)
      zh-cn: 長度8-30，必須包含三項（大寫字母、小寫字母、數字、 ()`~!@#$%^&*_-+=|{}[]:;<>,.?/ 中的特殊符號）
    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
      zh-cn: 交換器可用性區域
  VpcId:
    AssociationProperty: ALIYUN::ECS::VPC::VPCId
    Type: String
    Description:
      en: Please search the ID starting with (vpc-xxx) from console-Virtual Private Cloud
      zh-cn: 現有Virtual Private Cloud絡的執行個體ID
    Label:
      en: VPC ID
      zh-cn: Virtual Private Cloud執行個體ID
  VSwitchId:
    AssociationProperty: ALIYUN::ECS::VSwitch::VSwitchId
    AssociationPropertyMetadata:
      VpcId: ${VpcId}
      ZoneId: ${ZoneId}
    Type: String
    Description:
      en: Instance ID of existing business network switches, console-Virtual Private Cloud-VSwitches under query
      zh-cn: 現有業務網路交換器的執行個體ID
    Label:
      en: VSwitch ID
      zh-cn: 交換器執行個體ID
# 資源配置
Resources:
  EcsSecurityGroup:
    Type: ALIYUN::ECS::SecurityGroup
    Properties:
      SecurityGroupName:
        Ref: ALIYUN::StackName
      VpcId:
        Ref: VpcId
      # 安全性群組入連接埠
      SecurityGroupIngress:
        - PortRange: 80/80
          Priority: 1
          SourceCidrIp: 0.0.0.0/0
          IpProtocol: tcp
          NicType: internet
  EcsInstanceGroup:
    Type: ALIYUN::ECS::InstanceGroup
    Properties:
      # 執行個體名
      InstanceName:
        Fn::Join:
          - '-'
          - - Ref: ALIYUN::StackName
            - '[1,4]'
      IoOptimized: optimized
      # 付費類型
      InstanceChargeType:
        Ref: PayType
      PeriodUnit:
        Ref: PayPeriodUnit
      Period:
        Ref: PayPeriod
      # 網路設定
      VpcId:
        Ref: VpcId
      ZoneId:
        Ref: ZoneId
      VSwitchId:
        Ref: VSwitchId
      SecurityGroupId:
        Ref: EcsSecurityGroup
      # 磁碟類型和大小
      SystemDiskCategory: cloud_essd
      SystemDiskSize: 200
      MaxAmount: 1
      # 鏡像
      ImageId: centos_7
      # 執行個體類型
      InstanceType:
        Ref: EcsInstanceType
      Password:
        Ref: InstancePassword
      # 公網開啟
      AllocatePublicIP: true
      # 公網頻寬
      InternetMaxBandwidthOut: 1
  ECSRunCommand:
    Type: ALIYUN::ECS::RunCommand
    Properties:
      InstanceIds:
        Fn::GetAtt:
          - EcsInstanceGroup
          - InstanceIds
      Type: RunShellScript
      Sync: true
      Timeout: 3600
      CommandContent: |-
        #!/bin/bash

# 定義輸出
Outputs:
  # 將公網ip做為http返回的地址顯示在控制台
  Endpoint:
    Description:
      zh-cn: 對外暴露的公網IP地址
      en: Public IP Addresses
    Value:
      Fn::Sub:
        - http://${ServerAddress}
        - ServerAddress:
            Fn::Select:
              - 0
              - Fn::GetAtt:
                 - EcsInstanceGroup
                 - PublicIps
Metadata:
  ALIYUN::ROS::Interface:
    # 分組資訊
    ParameterGroups:
      - Parameters:
          - PayType
          - PayPeriodUnit
          - PayPeriod
        Label:
          default:
            en: PayType Configuration
            zh-cn: 付費類型配置
      - Parameters:
          - EcsInstanceType
          - InstancePassword
        Label:
          default:
            en: ECS Instance Configuration
            zh-cn: ECS執行個體配置
      - Parameters:
          - ZoneId
          - VpcId
          - VSwitchId
        Label:
          default:
            zh-cn: 選擇已有基礎資源
            en: Choose existing Infrastructure

模板中主要定義了參數（Parameters）、資源（Resources）、輸出（Outputs）以及中繼資料（Metadata）：

Parameters

參數（Parameters）定義了使用者在建立服務執行個體時，需要設定的參數。本文樣本中，Parameters中包含以下參數：

參數名稱	參數描述
PayType	付費類型
PayPeriodUnit	購買資源時間長度周期
PayPeriod	購買資源時間長度
EcsInstanceType	執行個體類型
InstancePassword	執行個體密碼
ZoneId	交換器可用性區域
VpcId	Virtual Private Cloud執行個體ID
VSwitchId	交換器執行個體ID

Resources

資源（Resources）定義了需要建立的資源，以及每一個資源套件含的Type和Properties。本文樣本中，Resources中包含的資源如下表所示。

ROS中定義的資源類型	資源說明
ALIYUN::ECS::SecurityGroup	建立ECS安全性群組
ALIYUN::ECS::InstanceGroup	建立ECS執行個體
ALIYUN::ECS::RunCommand	在ECS執行個體中執行Shell指令碼

說明

針對每一種阿里雲的資源類型，您都可以在資源類型索引處尋找其文法、屬性和傳回值（即輸出參數），用於編寫模板時的參考，以申明對於資源的具體要求。

Outputs

輸出（Outputs）定義了使用者建立服務完畢後，需要輸出的資訊。本文樣本中，Outputs以Endpoint（http://PublicIp） 作為輸出。使用者在資源建立完畢後，即可擷取訪問服務的地址。

Metadata

中繼資料（Metadata）不僅支援對Parameters中定義的參數進行分組，還支援對自訂參數進行隱藏，您可以在Resource Orchestration Service控制台的配置參數頁面查看效果。本文樣本中，參數分組如下：

分組名稱	參數名稱
PayType Configuration	PayType
	PayPeriodUnit
	PayPeriod
ECS Instance Configuration	EcsInstanceType
ECS Instance Configuration	InstancePassword
Choose existing Infrastructure	ZoneId
	VpcId
	VSwitchId

您還可以使用進階功能Mappings、Conditions，進階功能的詳細資料，請參見模板結構說明。

您還可以使用Terraform建立模板，詳細操作請參見建立Terraform類型模板。

在ROS控制台驗證模板

完成模板編寫後，您可以通過ROS控制台建立資源棧進行驗證。

登入ROS控制台。
在左側導覽列中，單擊資源棧。
在頁面左上方，選擇建立資源棧。
在建立資源棧頁面，完成頁面資訊配置。
1. 在指定模板框中，可以選擇選擇已有模板，將之前編寫完成的模板複製到模板內容中；也可以選擇使用樣本模板，選擇樣本模板呈現在模板內容中後進行修改。
2. 單擊下一步，進入配置參數頁面，檢查參數的正確性。並通過預覽模板資源功能驗證資源設定是否正確。
3. 可選：單擊下一步，進入合規預檢 (可選)頁面。完成頁面資訊配置。
4. 可選：單擊下一步，進入檢查並確認(可選)頁面，確認配置資訊。
5. 單擊建立。
說明
配置資源棧(可選)和檢查並確認(可選)為可選步驟，可根據實際規劃選擇是否需要執行這兩步。

建立資源棧成功即表示模板校正成功，如果建立失敗，請查看失敗原因，並調整模板。