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