架构描述了 Deployment Manager 模板的规范。如果模板已有对应的架构,Deployment Manager 将使用该架构强制规定用户如何与对应的模板进行交互。架构定义了一组规则,如果配置文件要使用特定模板,则必须符合这些规则。
除了定义模板的规则之外,架构还可让用户与您编写的模板交互,而不需要查看和了解每个模板层。用户只需查看架构中定义的要求,即可了解相应模板有哪些可设置或者必需的属性。
例如,您可以创建一个架构,其对应的模板必须始终定义一组特定的必需属性,并且每个属性都有自己的规范。一个属性必须是字符串,另一个必须是小于 100 的整数,等等。如果用户想在其配置中应用您的模板,可以查看架构并在其配置中设置正确的属性。
准备工作
- 如果要使用本指南中的命令行示例,请安装 “gcloud” 命令行工具。
- 如果希望使用本指南中的 API 示例,请设置 API 访问权限。
- 了解如何创建基本模板。
- 了解如何创建配置
- 了解 JSON 架构。
示例架构
这是一个名为 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
字段包含属性字段中(部分)元素的列表,这些是使用该架构的模板中必需的元素。此 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
当您使用 gcloud
命令行工具创建部署时,Deployment Manager 会自动为您上传配置的所有相关模板。同样,如果有任何架构文件(由附加的 .schema
格式标识),Deployment Manager 将在尝试创建任何资源之前,上传架构并根据架构验证部署。
要使用架构,只需将架构与模板和配置包含在同一本地目录中,然后像平常一样创建部署。gcloud
工具会检测架构文件并将其传递给 Deployment Manager。
API
按照说明在 API 中创建部署,并将架构文件与请求正文内联,方法与您添加模板时一样。