使用結構定義

結構定義的用途是說明 Deployment Manager 範本的規格。如果範本存在結構定義，Deployment Manager 會使用該結構定義來強制實行使用者與對應範本互動的方式。結構定義會定義一組規則，設定檔必須符合這些規則，才能使用特定範本。

除了定義範本的規則外，結構定義也可讓使用者透過介面來連接您編寫的範本，而不必查看及瞭解範本的每一層。使用者只需查看結構定義中所定義的要求即可，無須瞭解各個範本能設定或需要哪些屬性。

舉例來說，您可以建立一個結構定義，其中對應的範本一律必須定義一組特定的必要屬性，而且每個屬性都必須具有自己的規格。某一個屬性必須是字串，而另一個則必須是小於 100 的整數，依此類推。如果使用者想要在其設定中套用您的範本，該使用者必須查看結構定義，並在設定中設定正確的屬性。

事前準備

• 如要使用本指南提供的指令列範例，請安裝 `gcloud` 指令列工具。
• 如要使用本指南提供的 API 範例，請設定 API 存取權。
• 瞭解如何建立基本範本。
• 瞭解如何建立設定。
• 瞭解 JSON 結構定義。

結構定義範例

範例結構定義是為 Jinja 範本引擎編寫。如果您使用其他範本引擎，副檔名會有所不同，範本語法也可能不同。

以下是名為 vm-instance-with-network.jinja.schema 的簡單結構定義檔案：

info:
  title: VM Template
  author: Jane
  description: Creates a new network and instance
  version: 1.0

imports:
- path: vm-instance.jinja # Must be a relative path

required:
- IPv4Range

properties:
  IPv4Range:
    type: string
    description: Range of the network

  description:
    type: string
    default: "My super great network"
    description: Description of network

該結構定義適用於以下範本 (vm-instance-with-network.jinja)：

resources:
- name: vm-1
  type: vm-instance.jinja

- name: a-new-network
  type: compute.v1.network
  properties:
    IPv4Range: {{ properties['IPv4Range'] }}
    description: {{ properties['description'] }}

如果使用者想要在自己的設定中使用此範本，透過查看結構定義即可瞭解必須定義一個必要屬性 (IPv4Range)，以及一個可省略或包含的選用屬性 (description)。使用者接著能夠建立類似的設定檔，並確保提供名為 IPv4Range 的屬性：

imports:
- path: vm-instance-with-network.jinja

resources:
- name: vm-1
  type: vm-instance-with-network.jinja
  properties:
    IPv4Range: 10.0.0.1/16

結構定義的架構

以下是結構定義文件的範例。Deployment Manager 建議使用 YAML 格式的結構定義，但您也能以 JSON 編寫結構定義，Deployment Manager 也接受該格式。

Deployment Manager 接受根據 JSON 結構定義規格第 4 版草稿所編寫的結構定義。

<mongodb.py.schema>
info:
  title: MongoDB Template
  author: Jane
  description: Creates a MongoDB cluster
  version: 1.0

imports:
  - path: helper.py
    name: mongodb_helper.py

required:
  - name

properties:
  name:
    type: string
    description: Name of your Mongo Cluster

  size:
    type: integer
    default: 2
    description: Number of Mongo Slaves

  zone:
    type: string
    default: us-central1-a
    description: Zone to run
    metadata: gce-zone

有效的結構定義檔案是 JSON 結構定義檔案，並新增 info 和 imports 這兩個頂層欄位。以下是各個欄位及其有效內容的簡短說明。

資訊

info 屬性包含有關結構定義的中繼資訊，當中包含標題、版本編號和說明等資訊。

請至少在這項屬性中提供標題和說明。

imports

imports 欄位含有一份清單，當中列出使用此結構定義的範本所需的對應檔案。隨著範本上傳的結構定義具有匯入項目清單時，Deployment Manager 會檢查 imports 屬性中的所有檔案是否已經與範本一併上傳。

在這個 imports 欄位中指定檔案時，您可以從設定的 imports 欄位中省略該檔案。在上述範例中，imports 欄位會匯入名為 vm-instance.jinja 的檔案：

imports:
- path: vm-instance.jinja

在對應的設定檔中，使用者可以省略匯入 vm-instance.jinja 檔案的程序，因為當 Deployment Manager 檢查範本的結構定義時，該檔案將會自動匯入。

匯入路徑必須與結構定義檔案的位置相關。這樣可讓您將範本、結構定義和設定均儲存在同一個目錄中，並確保在共用或移動目錄時，這些檔案能具備有效的匯入項目。

必填

required 欄位包含一份清單，其中列出在使用結構定義的範本中必要屬性欄位的元素。未在這個 required 欄位中指定的任何元素皆視為選用元素。

屬性

properties 欄位包含此文件的 JSON 結構定義規則。範本的使用者可設定 properties 欄位中說明的元素。您可以針對這些屬性使用所有支援的 JSON 結構定義驗證，例如：

• type (字串、布林、整數、數字等)
• default
• minimum / exclusiveMinimum / maximum / exclusiveMaximum
• minLength / maxLength
• pattern
• not X / allOf X, Y / anyOf X, Y / oneOf X, Y

建議您至少提供欄位的 type 和 description，以便使用者瞭解屬性可接受的值。如為選用屬性，最好也包含 default 值。

如需驗證關鍵字的清單，請參閱 JSON 結構定義驗證說明文件。

設定任意中繼資料

根據預設，Deployment Manager 會忽略任何無效的 JSON 結構定義欄位。如需擴充結構定義來包含專用欄位或屬性，您可以任意建立需要的屬性並將其加入結構定義，只要該欄位或屬性不會與任何 JSON 結構定義驗證關鍵字重疊即可。

例如，您可以加入用來註解您其中一個屬性的中繼資料欄位：

properties:
  zone:
    type: string
    default: us-central1-a
    description: Zone to run
    metadata: a-special-property

或者，您也能建立可能會在 Deployment Manager 以外的其他應用程式中使用的特殊變數：

properties:
  size:
    type: integer
    default: 2
    description: Number of Mongo Slaves
    variable-x: ultra-secret-sauce

建立結構定義

結構定義是一個獨立文件，並以其說明的範本命名。結構定義必須使用與對應範本相同的名稱來命名，並且在結尾附加 .schema：

TEMPLATE_NAME.EXTENSION.schema

舉例來說，如果範本名為 vm-instance.py，對應的結構定義檔案就必須命名為 vm-instance.py.schema。每個範本只能有一個結構定義。

結構定義可以包含結構定義的結構一節中說明的一或多個欄位。或者，您也可以使用 JSON 來編寫結構定義。如需 JSON 結構定義的範例，請參閱 JSON 結構定義說明文件。

使用結構定義

後續步驟

• 瞭解範本。
• 使用範本屬性進一步擷取內容。
• 使用環境變數填入專案和部署作業的相關資訊。
• 將範本永久加入專案做為複合類型。