語法參照

本頁說明 Deployment Manager 使用的語法。如需瞭解設定和範本適用哪些語法,您可以使用這份指南做為參考。

設定和範本的語法

基本語法

  • resources - 要建立的一組資源。
    • name - 為這項資源建立的執行個體名稱。
    • type - 資源類型。這個值可以是 compute.v1.instance 等基礎類型,也可以是匯入的範本。如要查看支援資源的完整清單,請參閱支援的資源類型說明文件。
    • properties - 這項資源的屬性。相關資訊請見範本屬性
    • metadata - 這項資源的其他設定。請查看中繼資料的欄位清單。

範例

resources:
- name: vm-instance
  type: compute.v1.instance
  properties:
    machineType: zones/us-central1-a/machineTypes/n1-standard-1
    ...

存取權控管

如要為資源設定 IAM 政策,請使用 accessControl 區段:

  1. 針對您要套用存取權控管政策的各項資源,將 accessControl 區段新增至資源的頂層設定。

  2. 指定資源所需的 gcpIamPolicy。每項 IAM 政策可包含繫結清單。各繫結均會將一組成員連結至某個角色。

如要進一步瞭解如何管控資源存取權,請參閱在設定中進行存取權控制設定一文。

舉例來說,下列 accessControl 區段可新增繫結,將這些角色授予使用者。

使用者 角色
alice@example.com roles/pubsub.editor
  • my-other-app@appspot.gserviceaccount.com
  • jane@example.com
roles/pubsub.publisher
resources:
- name: a-new-pubsub-topic
  type: pubsub.v1.topic
  properties:
    ...

  accessControl:
    gcpIamPolicy:
      bindings:
      - role: roles/pubsub.editor
        members:
        - "user:alice@example.com"
      - role: roles/pubsub.publisher
        members:
        - "user:jane@example.com"
        - "serviceAccount:my-other-app@appspot.gserviceaccount.com"

參照

如要進一步瞭解參照的使用時機和其他範例,請參閱建立參照

您可以使用對其他資源屬性的參照,而非直接提供值。例如,如要建立執行個體群組管理員,以便使用同一項部署作業中的執行個體範本,您可以透過語法 $(ref.instance-template.selfLink) 使用參照,而不必明確輸入執行個體範本的完整連結。

如要查看您可以建立參照的屬性,請參閱資源 API 的 get 方法。例如,如需 VM 執行個體所有屬性的清單,請參閱 instances.get() 方法的回應。

您可以使用與 JSONPath「dot」標記法類似的語法來宣告參照。您可以使用下列語法來宣告參照:

$(ref.RESOURCE_NAME.PATH_TO_PROPERTY)

針對 Compute Engine 執行個體的網路介面等清單屬性,請使用下列語法:

$(ref.RESOURCE_NAME.LIST_PROPERTY[index].ITEM)

範例

$(ref.exampleInstance.networkInterfaces[0].natIp)
$(ref.exampleInstance.serviceAccounts[0].email)

使用部署作業專屬的環境變數

建立部署作業時,Deployment Manager 會建立環境變數,當中包含部署作業的相關資訊,例如目前的專案名稱、部署作業的名稱等。

如需可用環境變數的完整清單,請參閱環境變數

如何使用環境變數:

{{ env["deployment"] }} # Jinja

context.env["deployment"] # Python

範例

- type: compute.v1.instance
  name: vm-{{ env["deployment"] }}

範本屬性

範本屬性是由您建立的任意屬性。您可以宣告範本屬性,並在頂層設定中設定屬性值,這樣就不需要直接在範本中提供固定的屬性與值,也不必對值進行硬式編碼。如要建立範本屬性,請使用下列語法:

{{ properties["property-name"] }} # Jinja

context.properties["property-name"] # Python

接著在頂層設定或上層範本中設定屬性值:

imports:
- path: vm_template.jinja

resources:
- name: my-vm
  type: vm_template.jinja
  properties:
   property-name: example-value

進一步瞭解範本屬性

輸出

在輸出區段中,您可以定義任意鍵/值組合來公開部署作業的特定資訊。在提供鍵之後,您可以將值設為靜態字串、屬性參照、範本變數或環境變數。

  • outputs - 宣告使用者可在資源屬性中呼叫的輸出清單。
    • name - 輸出屬性的名稱。
    • value - 輸出屬性的值。

範例

resources:
- name: vm-instance
  type: compute.v1.instance
  ...

outputs:
- name: databaseIp
  value: $(ref.vm-instance.networkInterfaces[0].natIp)
- name: databaseName
  value: example-database

進一步瞭解輸出

中繼資料

metadata 區段包含特殊中繼資料,可供您分別套用至各項資源。Deployment Manager 具有觸發特定功能的專屬中繼資料。例如,dependsOn 功能需要中繼資料項目才能運作。

依存

dependsOn 屬性會在資源之間建立明確的依存關係。例如,指定資源 A 依存於資料 B,即可確保系統一律會在建立資源 B 後才建立資源 A。

metadata: the metadata for this resource
  dependsOn: Any explicit dependencies to another resource.

範例

resources:
- name: vm-instance
  type: compute.v1.instance
  properties:
    machineType: zones/us-central1-a/machineTypes/n1-standard-1
    ...
  metadata:
    dependsOn:
    - persistent-disk-1
    - a-new-network-1

進一步瞭解如何建立明確的依存關係

結構定義的語法

結構定義可讓您控制使用者與範本的互動方式。以下是可用於結構定義檔案中的語法。 進一步瞭解結構定義

info

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

這個屬性中,名稱和說明為必填項目。

範例

info:
  title: MongoDB Template
  author: Jane
  description: Creates a MongoDB cluster
  version: 1.0

imports

imports 欄位含有一份清單,當中列出使用此結構定義的範本所需的對應檔案。如果您在上傳範本時提供含有匯入清單的結構定義,Deployment Manager 就會檢查是否已隨範本上傳 imports 屬性中的所有檔案。

範例

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

required

required 欄位包含使用結構定義的範本所需的屬性欄位元素清單。系統會將未於 required 欄位中指定的元素視為選填項目。

範例

required:
  - name

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

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

屬性

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

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

建議您至少提供欄位的類型和說明,以便使用者瞭解屬性可接受的值。即便是選填屬性,也建議您使用預設值。

如需取得驗證關鍵字清單,請參閱 JSON 結構定義驗證說明文件

範例

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

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

後續步驟