使用架构

架构描述了 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 中创建部署，并将架构文件与请求正文内联，方法与您添加模板时一样。

后续步骤