資源編排模板詳解

資源編排中的模板，是對一組資源的定義和描述。您可以按照模板語法和資源的屬性，編寫自己的模板，也可以直接使用阿里雲提供的模板樣例。目前，支援20多種阿里雲資源的編排服務。本文將對阿里雲資源和資源編排模板分別進行介紹。

1. 資源

開始編寫模板之前，您需要對所需的資源有所瞭解。

資源Type

一個資源型別，對應一種阿里雲資源，是每種資源的唯一標識。您可以查閱資源型別列表。

例如，阿里云云伺服器的資源型別是 ALIYUN::ECS::Instance。

資源Properties

列出了當前資源支援的所有可配置屬性。

如上圖所示，雲伺服器的可配置屬性有 SecurityGroupId, InstanceType, ImageId等。歸根結底，編寫模板就是編輯資源，您可以通過配置資源的屬性來自定義資源。在後設資料中，清楚了描述了每個屬性的特性。下面介紹幾個比較重要的特性：

• key: 屬性關鍵字。通過它來標識您要配置當前資源的哪個屬性。
• type: 表明當前屬性值是什麼型別。您在給屬性賦值的時候，型別一定要匹配。否則在建立模板的時候，語法檢查會不通過。
• required: 表明此屬性是否是必須配置項。如果某項屬性被標記為 required為 true，那麼這個屬性是必須要配置的。例如，資源 ALIYUN::ECS::Instance 的 SecurityGroupId, InstanceType 和 ImageId 三個屬性都被標記為 required ，那麼當您編輯 ALIYUN::ECS::Instance 型別的資源的時候，這三個屬性的配置是不能省略的。

• constraints: 表明當前屬性是否有其他約束。例如，DiskMappings 的constraints如下：

  [ { "length": { "max": 4 } } ]

  表明DiskMappings的值的長度不能超過4，同時DiskMappings的type為list，那麼當您給DiskMappings賦值時，要配置成長度不好過4的陣列。

資源Attributes

Attributes 列舉了當前資源的所有可獲取屬性，以及屬性的描述資訊。

如上圖所示，雲伺服器的可獲取屬性有 InstanceId, ZoneId等。可獲取屬性，可以在 Resources 和 Outputs 兩部分中進行獲取。例如，下面模板片段定義了一個名為WebServer的 ALIYUN::ECS::Instance 資源，在Outputs部分通過Fn::GetAtt方法，獲取到WebServer的例項ID。

"Resources" : {
  "WebServer": {
    "Type": "ALIYUN::ECS::Instance",
    "Properties": {
      "ImageId" : {"Ref": "ImageId"},
      "InstanceType": {"Ref": "InstanceType"},
      "SecurityGroupId": {"Ref": "SecurityGroupId"}
    }
  }
},
"Outputs": {
  "InstanceId": {
       "Value" : {"Fn::GetAtt": ["WebServer","InstanceId"]}
  }
}

2. 模板

接下來，會對資源編排模板進行詳細的介紹。模板是一個 JSON 格式的文字檔案。一般而言，模板分為六個部分：ROSTemplateFormatVersion, Description, Parameters, Mappings, Resources 和 Outputs。 格式如下：

{
  "ROSTemplateFormatVersion" : "2015-09-01",

  "Description" : "模板描述",

  "Parameters" : {
  },

  "Mappings" : {
  },

  "Resources" : {
  },

  "Outputs" : {
  }
}

其中，只有 ROSTemplateFormatVersion 是 必須指定 的部分。

• ROSTemplateFormatVersion: 指定模板格式的版本，目前僅支援值 2015-09-01。
• Description: 模板的描述資訊

下面對 Parameters, Mappings, Resources, Outputs 逐一說明。

2.1 Resources

描述資源棧中每個資源，以及資源之間的關係。一個資源可以被其他資源和 Outputs 所引用。

Resources 語法

"Resources" : {
    "資源 ID" : {
        "Type" : "資源型別",
        "Properties" : {
        },
        "DeletionPolicy" : "Retain",
        "DependsOn": "資源"
    }
}

• 資源 ID: 是資源在當前模板中的唯一標識，可以被其他的部分引用。您可以任意設定。
• Type: 標識當前資源的型別，參考資源型別

• Properties:

  • 您可以給此資源配置任意多個屬性，做為建立物理資源的引數和值。每種資源的可配置屬性，可以通過 ROS控制檯 -> 資源型別 -> 屬性資料 來檢視。例如，ECS Instance 的 Properties 地址。
  • 屬性值型別可以是字串、字串列表、布林值，也可以引用Parameters。下面是一個簡單的例子，資源WebServer的屬性 ImageId 和 SecurityGroupId 分別引用引數 ImageIdRef 和 SecurityGroupId 引數。有關 Parameters 的詳解見下節。

    {
      "ROSTemplateFormatVersion" : "2015-09-01",
      "Description": "ecs例項，指定imageId",
      "Parameters" : {
        "ImageIdRef": {
          "Type" : "String",
          "Description": "映象檔案 ID，表示啟動例項時選擇的映象資源"
        },
        "SecurityGroupId": {
          "Type": "String",
          "Description": "安全組Id"
        }
      },
      "Resources" : {
        "WebServer": {
          "Type": "ALIYUN::ECS::Instance",
          "Properties": {
            "ImageId" : {"Ref": "ImageIdRef"},
            "InstanceType": "ecs.t1.small",
            "SecurityGroupId": {"Ref": "SecurityGroupId"}
          }
        }
      }
    }
  

• DeletionPolicy: 配置此屬性，可以在資源棧被刪除時 保留 該資源
• DependsOn: 指定資源的建立順序。下面是一個簡單的例子，DatabaseServer 將在 WebServer 建立成功後才開始建立。

{
  "ROSTemplateFormatVersion" : "2015-09-01",
  "Description": "先建立DBServer, 再建立WebServer",
  "Parameters" : {
    "SecurityGroupId": {
      "Type": "String",
      "Description": "安全組Id"
    }
  },
  "Resources" : {
    "WebServer": {
      "Type": "ALIYUN::ECS::Instance",
      "DependsOn": "DatabseServer"
    },
    "DatabseServer": {
      "Type": "ALIYUN::ECS::Instance",
      "Properties": {
        "ImageId" : "m-25l0rcfjo",
        "InstanceType": "ecs.t1.small",
        "SecurityGroupId": {"Ref": "SecurityGroupId"}
      }
    }
  }
}

2.2 Parameters

把可能會變化的值，放到Parameter中，讓模板變得更靈活。詳細描述請參考幫助文件。注意，這裡僅僅是把易變項抽象為引數而已，在建立資源棧的時候需要給每個引數賦值。

Parameters 語法

通過文件可知 Parameters 可以配置的屬性比較多，不過只有 Type 這個屬性是 必須設定 的。 格式如下：

"Parameters" : {
    "引數 ID" : {
        "Type" : "引數型別"
    }
}

• 引數 ID: 引數唯一標識，可以在 Resources 部分引用。
• Type: 引數的資料型別。支援 String, Number, CommaDelimitedList, Json, Boolean 五種資料型別。
• Default: 給引數配置預設值。建立資源棧的時候，如果您沒有顯示的給引數賦值，那麼將採用 Default值 。
• AllowedValues: 配置合法的引數值列表。您可以配置此項，來約束引數值的可選值。
• MaxLength 和 MinLength: 當引數的Type為 String 型別時，可以通過這兩個配置項來限定引數值的長度。
• MaxValue 和 MinValue: 當引數的Type為 Number 型別時，可以通過這兩個配置項來限定引數值的大小。
• NoEcho: 如果您希望呼叫查詢資源棧時隱藏引數值，可以設定 NoEcho: true

Parameters 示例

以下 Parameters 部分示例宣告兩個引數。

• InstanceType 引數型別是 String 型別，預設值是 ecs.t1.small ，允許值是 ecs.t1.small 和 ecs.t1.xsmall 兩種值。
• SecurityGroupPriority 引數型別是 Number ，可指定的最大值是 100 ，最小值是 1。

"Parameters" : {
    "InstanceType": {
      "Type": "String",
      "Default": "ecs.t1.small",
      "Description": "例項的資源規格",
      "AllowedValues": [
        "ecs.t1.xsmall",
        "ecs.t1.small"
      ]
    },
    "SecurityGroupPriority": {
      "Default": 1,
      "Description": "生成的安全組的優先順序，優先順序可選範圍為1-100，預設值為1，即最高優先順序。",
      "Type": "Number",
      "MinValue": 1,
      "MaxValue": 100
    }
}

2.3 Mappings

在 Mappings 部分，您可以配置多個列舉值或者對映表。在模板的 Resources 和 Outputs 部分可以使用 Fn::FindInMap 內部函式，通過給定 key 獲取 value。

Mappings 語法

映像部分由　Key-Value 對組成。其中 Key 和 Value 可以為字串型別或者數字型別。篩選某個值，搜尋深度為3。定義 Mappings，格式如下：

"Mappings" : {
    "ValidMapping" : {
        "TestKey1" : { "key1" : "value1" }
    }
}

獲取列舉值的方法如下：

{ "Fn::FindInMap" : [ "ValidMapping", { "Ref" : "TestKey1" }, "key1"]}

Mappings 示例

以下示例，展示型別是 ALIYUN::ECS::Instance 的資源 WebServer，其屬性 ImageId 根據 region 以及作業系統位數進行對映。

{
  "ROSTemplateFormatVersion": "2015-09-01",
  "Parameters": {
    "regionParam": {
        "Description": "選擇建立ECS的區域",
        "Type": "String",
        "AllowedValues": ["hangzhou", "beijing"]
    },
    "sysTypeParam": {
        "Description": "作業系統位數",
        "Type": "Number",
        "AllowedValues": [32, 64]
    },
    "SecurityGroupId": {
      "Type": "String",
      "Description": "安全組Id"
    }de
  },
  "Mappings" : {
    "RegionMap" : {
      "hangzhou" : { "32" : "m-25l0rcfjo", "64" : "m-25l0rcfj1" },
      "beijing" : { "32" : "m-25l0rcfj2", "64" : "m-25l0rcfj3" }
    }
  },
  "Resources": {
    "WebServer": {
      "Type": "ALIYUN::ECS::Instance",
      "Properties": {
        "ImageId" : { "Fn::FindInMap" : [ "RegionMap", { "Ref" : "regionParam" }, { "Ref" : "sysTypParam" }]},
        "InstanceType": "ecs.t1.small",
        "SecurityGroupId": {"Ref": "SecurityGroupId"}
      }
    }
  }
}

2.4 Outputs

當您呼叫查詢資源棧詳情介面的時候，資源編排服務會根據 Outputs 部分返回對應的值，往往用來獲取資源的屬性值。

Outputs 語法

輸出部分由 輸出ID 和 輸出值表示式 組成。格式如下：

"Outputs" : {
    "輸出 ID" : {
        "Description" : "輸出的描述",
        "Value" : {輸出值表示式}
    }
}

其中，輸出值表示式，使用內部函式 Fn::GetAtt 來獲取資源的屬性值。格式如下：

{"Fn::GetAtt": ["resourceId", "attributeId"]}

Outputs 示例

在以下示例中，分別獲取資源 WebServer 的 InstanceId 屬性和 PublicIp 屬性。

"Outputs": {
  "InstanceId": {
       "Value" : {"Fn::GetAtt": ["WebServer","InstanceId"]}
  },
  "PublicIp": {
       "Value" : {"Fn::GetAtt": ["WebServer","PublicIp"]}
  }
}

更多模板示例，請參考 ROS 模板樣例