添加模板“Capabilities”注释/解析/内省

https://blueprints.launchpad.net/heat/+spec/resource-capabilities

也与 https://blueprints.launchpad.net/heat/+spec/interface-types 相关

向 HOT 添加一个可选的注释，使模板作者能够定义模板实现/提供特定的能力。

问题描述

目前，环境资源注册表 (resource_registry) 提供了一个极其灵活但完全不受约束的接口，用于将类型别名映射到实现。

这使得那些希望使用资源注册表进行组合的人感到困难，特别是如果您希望为用户提供选择提供程序资源模板的特定实现的选择。

例如，考虑以下工作流程

1. 选择父模板。

2. 选择一组其他模板和环境（或以编程方式生成，例如从一个或多个已知位置/路径中提取模板）。

3. 检查该组以确定资源类型级别的能力/选项。这些是用户将要做的主要选择，以确定每个类型的嵌套堆栈实现。

4. 用户为每个具有多个选择的堆栈选择一个嵌套堆栈选项。

5. 重新检查给定这些主要选项，以获取完整的参数集，以便可以提示用户输入强制性和可选参数，包括那些未由顶级父模板公开的参数。

6. 用户输入所有参数的值，并且创建堆栈。

本规范的主题是上述步骤 3 和 4。https://review.openstack.org/#/c/197199 讨论了步骤 5。其他步骤已经可行。

以下讨论将重点放在 TripleO 用例上，因为这是驱动这项工作的原因（TripleO 通过 resource_registry 大量使用模板组合）。但是，该功能应该对任何希望使用 resource_registry 通过 resource_registry 从相互关联的模板树构建复杂环境的人都有用。

以下是 TripleO 控制器节点实现中使用的 resource_registry 映射的一个示例

resource_registry:
  OS::TripleO::Controller: puppet/controller-puppet.yaml
  OS::TripleO::Controller::Net::SoftwareConfig: net-config-bridge.yaml
  OS::TripleO::ControllerPostDeployment: puppet/controller-post-puppet.yaml
  OS::TripleO::ControllerConfig: puppet/controller-config.yaml
  OS::TripleO::Controller::Ports::ExternalPort: network/ports/noop.yaml
  OS::TripleO::Controller::Ports::InternalApiPort: network/ports/noop.yaml
  OS::TripleO::Controller::Ports::StoragePort: network/ports/noop.yaml
  OS::TripleO::Controller::Ports::StorageMgmtPort: network/ports/noop.yaml
  OS::TripleO::Controller::Ports::TenantPort: network/ports/noop.yaml
  OS::TripleO::Controller::CinderBackend: extraconfig/controller/noop.yaml

我们可以看到有很多选择（这只是完整环境的一个很小的子集），没有办法让 UI 确定任何映射的有效选择。直接在模板中描述有效的实现将是有益的，以便 UI/CLI 工具可以发现它们并在验证时进行约束。

以以上为例，需要做出多个选择

• 配置工具类型（所有 puppet/*.yaml 资源）

• NIC 配置（物理网络，例如桥接、绑定等）

• 端口分配（覆盖网络，其中 ports/noop.yaml 将所有端口分配给一个通用网络）

• 选择（可能多个 CinderBackend 实现）

为了简单起见，以下示例将仅考虑在 puppet 和其他实现之间的选择。

提议的变更

拟议的更改涵盖三个领域

• 注释 - 如何传达资源类型与可能满足该类型的模板之间的关系。

• 解析 - Heat 如何使用堆栈上的用户设置来选择最合适的模板来满足资源类型，从一个选项列表中。

• 内省 - UI 如何以编程方式使用注释向用户呈现一个界面，以便为每个符合条件的资源类型选择一个选项。

本更改的其余部分分为这三个部分。应该注意的是，并非所有三个部分对于最小可行功能都是必需的。有可能 Mitaka 的实现仅涵盖注释和内省 API，以便用户能够理解选择堆栈实现模板的“模式”（缺乏更好的词语）。

注释

添加一个可选的模板注释，受 TOSCA “substitution_mappings” 接口 [1] 启发，允许在 HOT 模板中添加一个可选的新块，模板作者可以在其中声明模板提供特定的能力。

正在提议两种略有不同的能力注释用法。

基于标签

例如，可能有多个有效的 OS::TripleO::Controller 实现。对于基于 Puppet 的实现，模板上的能力注释将指示它

heat_template_version: 2015-10-15

capabilities:
   deployment: puppet

此处使用的语法类似于 TOSCA 规范中定义的语法，但名称已调整为更好地匹配现有的 HOT 约定。capabilities 部分不会被严格验证；可以添加额外的键/值对，这些键/值对未在环境中指定，以便模板可以移植。

基于类型

也可以使用这些注释进行客户端发现，通过专门引用模板可以使用的资源类型名称，来发现要通过 resource_registry 传递的有效模板列表

heat_template_version: 2015-10-15

capabilities:
   resource_type: OS::TripleO::Controller

这应该支持列表，因为 TripleO 已经看到可以将用作计算机或控制器挂钩的模板的示例

heat_template_version: 2015-10-15

capabilities:
   resource_type: [OS::TripleO::ControllerPostDeployment,
                   OS::TripleO::ComputePostDeployment]

解析

在环境中，将添加一个可选的新“requires”部分，并支持 resource_registry 键包含多个实现的列表。然后，Heat 将能够通过将环境 requires 与具有（希望匹配的）能力的模板列表进行匹配来解析应选择的实现。如果找到零个或多个实现，将抛出验证错误。

例如，扩展前一节的示例，以下是环境文件

requires:
   deployment: puppet

resource_registry:
   OS::TripleO::Controller: [puppet/controller.yaml, docker/controller.yaml]

将注释添加到两个引用的模板，我们有

puppet/controller.yaml

heat_template_version: 2015-10-15

capabilities:
   deployment: puppet

docker/controller.yaml

heat_template_version: 2015-10-15

capabilities:
   deployment: docker

将这三个文件放在一起，Heat 将使用 capabilities 部分来确定使用哪个 controller.yaml 文件。

内省

在 注释 部分中描述的功能提供了足够的信息，以便 Heat 提供一系列内省查询，以促进用户体验。

特定类型查询

给定特定的资源类型名称，Heat API 应该能够返回声明支持该类型的模板列表（注意：这取决于使用上述 基于类型 注释样式）。

通过 Heat 客户端对这种查询的潜在输出示例如下

$ heat capabilities-find -r -c resource_type=OS::TripleO::Controller ./*
puppet/controller.yaml
docker/controller.yaml

这将从当前目录递归检查每个模板中的能力，返回与所需的capabilities匹配的模板列表（如果需要，可以通过传递多个 -c 选项来实现）。这使得客户端可以发现多个实现。

能力摘要

还需要让 Heat 分析一系列模板和环境，返回可以指定的capabilities列表

例如，给定上述 Puppet 和 Docker 示例模板

$ heat template-capabilities -f puppet/controller.yaml \
                             -f docker/controller.yaml

这将返回

{
  'deployment': ['puppet', 'docker']
}

如果使用 基于类型 注释，则存在类似调用的版本

{
  'OS::TripleO::Controller': ['puppet/controller.yaml',
                              'docker/controller.yaml']
}

操作员或 UI 然后知道这些是可以在堆栈创建过程中解析的选项。请注意，这与发布的递归验证规范 [2] 相关，但不同，后者是关于暴露堆栈创建所需的参数，而不是与有效组合相关的选项。

注意

API v. 客户端

该规范的最初迭代是谈论让 Heat 客户端遍历模板树并执行描述的内省。此后已更改为引用 Heat API，将逻辑移至服务器端，并允许非 Python 客户端访问此功能。

参考资料

[1]

http://docs.oasis-open.org/tosca/TOSCA-Simple-Profile-YAML/v1.0/csd03/TOSCA-Simple-Profile-YAML-v1.0-csd03.html#_Toc419746122

[2]

https://review.openstack.org/#/c/197199

备选方案

讨论的主要替代方案（参见此补丁的先前版本）是在 resource_registry 中添加约束，以便可以在环境内部定义有效的映射。这个想法被拒绝，因为希望有一个更可发现的界面（例如，查找有效的实现与严格定义的约束列表）。

另一个后续提案也被拒绝，它侧重于仅匹配模板中的 resource_type 注释，有人建议这不够精细且不够灵活。

实现

实现将需要在 Mitaka HOT 版本中添加新的 capabilities 注释，这将是可选的，如果省略，将保持现有行为。

然后将向环境添加支持，以允许通过 resource_registry 传递列表，并通过新的 requires 部分进行解析。

负责人

主要负责人

• shardy

• jdob

里程碑

完成目标里程碑

mitaka-2

工作项

对引擎的更改

• 更新 HOT 以支持可选的新 capabilities 注释

• 更新环境代码以允许 resource_registry 的列表

• 更新环境以处理 capabilities 部分以过滤列表

对 heatclient 的更改

• 为 python-heatclient 添加支持，以解析模板树，返回指定 capability 的有效模板列表

• 添加支持以传递文件/环境以获取所需的 capabilities

文档更改

• 在模板指南 docs/HOT 规范中记录新的接口。

依赖项

无