语法参考

本页面描述了 Deployment Manager 使用的语法。以本指南作为参考,了解在配置和模板中使用的语法。

用于配置和模板的语法

基本语法

  • resources - 待创建的一组资源。
    • name - 对此资源进行实例化后的名称。
    • type - 资源类型。此类型可以是基本类型(例如 compute.v1.instance)、类型提供程序(例如 gcp-types/compute-v1:addresses)或导入的模板。请参阅支持的类型提供程序列表
    • properties - 此资源的属性。如需了解说明,请参阅模板属性
    • metadata - 此资源的额外配置。查看元数据中的字段列表。

示例

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

accessControl

如果要对资源设置 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 方法。例如,如需查看虚拟机实例的所有属性的列表,请参阅 instances.get() 方法的响应。

您可以使用与 JSONPath “.” 符号类似的语法来声明引用。使用以下语法来声明引用:

$(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 部分中,您可以定义公开您部署特定信息的任意键/值对。您提供键并将值设置为静态字符串、属性的引用、模板变量或环境变量。

  • outputs - 声明用户可以在其资源属性中调用的 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

dependsOn 属性在您的资源之间创建显式依赖关系。例如,指定资源 A 依赖于资源 B 可确保始终在资源 A 之前先创建资源 B。

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 字段包含使用此架构的模板所需的相应文件的列表。如果您上传的模板对应的架构包含 imports 列表,则 Deployment Manager 会检查 imports 属性中的所有文件是否与模板一起上传。

示例

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

必需

required 字段包含属性字段中的元素列表,使用该架构的模板中需要这些元素。此 required 字段中未指定的任何元素会被视为可选元素。

示例

required:
  - name

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

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

properties

properties 字段包含此文档的 JSON 架构规则。properties 字段中描述的元素可由模板用户设置。您可以对这些 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 架构验证文档,获取验证关键字列表。

示例

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

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

后续步骤