使用架构

架构描述了 Deployment Manager 模板的规范。如果模板已有对应的架构，Deployment Manager 将使用该架构强制规定用户如何与对应的模板进行交互。架构定义了一组规则，如果配置文件要使用特定模板，则必须符合这些规则。

除了定义模板的规则之外，架构还可让用户与您编写的模板交互，而不需要查看和了解每个模板层。用户只需查看架构中定义的要求，即可了解相应模板有哪些可设置或者必需的属性。

例如，您可以创建一个架构，其对应的模板必须始终定义一组特定的必需属性，并且每个属性都有自己的规范。一个属性必须是字符串，另一个必须是小于 100 的整数，等等。如果用户想在其配置中应用您的模板，可以查看架构并在其配置中设置正确的属性。

准备工作

示例架构

示例架构是为 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 将接受 JSON 架构。

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

info 属性包含有关架构的元信息，其中包括标题、版本号和说明等信息。

此属性中至少应提供标题和描述。

imports

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

当您在此导入字段中指定了某个文件时，可以在配置的 imports 字段中省略该文件。在上面的示例中，imports 字段导入了文件名 vm-instance.jinja：

imports:
- path: vm-instance.jinja

在相应的配置文件中，用户可以省略导入 vm-instance.jinja 文件，因为当 Deployment Manager 检查模板的架构时，会自动导入该文件。

导入路径必须相对于架构文件的位置。这样，您就可以将模板、架构和配置存储在同一目录中，并确保在共享或移动目录时文件拥有有效的导入项。

必填

required 字段包含属性字段中（部分）元素的列表，这些是使用该架构的模板中必需的元素。此 required 字段中未指定的任何元素均被视为可选元素。

properties

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 架构文档。

使用架构

gcloud


当您使用 Google Cloud CLI 创建部署时，Deployment Manager 会自动为您上传配置的所有相关模板。同样，如果有任何架构文件（由附加的 .schema 格式标识），Deployment Manager 将在尝试创建任何资源之前，上传架构并根据架构验证部署。

要使用架构，只需将架构与模板和配置包含在同一本地目录中，然后像平常一样创建部署。gcloud CLI 会检测架构文件并将其传递给 Deployment Manager。

API


按照说明在 API 中创建部署，并将架构文件与请求正文内联，方法与您添加模板时一样。

后续步骤