资源属性发现 API¶

https://blueprints.launchpad.net/blazar/+spec/resource-properties-discovery-api

我们建议添加一个 API，允许用户检索所有可能的资源属性列表：每个资源类型支持哪些键，以及这些键的有效值范围。这将允许用户更精确地构建资源请求，并允许在工具和 Horizon 控制台中实现更高级的工作流程。

问题描述¶

目前，只有操作员被允许枚举 Blazar 中注册的资源。用户可以发出租赁请求并提供资源约束，但没有办法确定哪些约束是有效/可能的。提供一种允许用户了解允许哪些资源键和值的机制可以改善预订的用户体验。

用例¶

作为用户，我知道我可以基于资源属性预留资源。我想知道我的目标资源池有哪些资源属性，以便有效地利用此功能。
作为操作员，我希望用户能够自动发现我对 Blazar 资源所做的更改，而无需宣布它们或以其他方式更新单独的文档集。
作为 CLI 用户，我希望能够检索资源属性列表，以便为预订提出未来的有效 CLI 请求。

提议的变更¶

我们建议添加一个新的 REST API 端点，该端点对于每种资源类型，返回资源属性列表及其可能的值。此 API 可以暴露给用户直接查询。

备选方案¶

与其向用户暴露新的 API，不如可以在 blazar-dashboard 插件中实现一个更好的用户界面。可以使用管理员令牌获取所有资源的列表，并从那里读取属性并在多种方式下呈现给用户。但是，Horizon 的通用模式是使用用户的令牌进行所有请求，并且添加管理员令牌需要使用 Blazar 服务用户凭据配置 Horizon。

另一种选择是允许用户获取 Blazar 资源本身并进行自己的检查。默认情况下，只有管理员被允许列出和查看资源。操作员可以放宽此限制，但这会冒着意外暴露有关资源的敏感数据的风险。此外，此工作流程不太直观，并且在比较大量资源时无法很好地扩展。

数据模型影响¶

额外的功能将获得一个额外的属性，private，它将它们标记为不可枚举。这允许操作员向资源添加敏感元数据，而不必担心将其暴露给用户。

“private” 功能的概念以前不存在，并且假设给定属性对于所有资源要么是私有的，要么是公共的。API 不支持将某些资源的私有值与其他资源的公共值设置不同。但是，现有的数据模型在理论上支持这一点，因为功能不是以正常形式存储的（它们只是具有给定键、值和附加资源 ID 的行）。

为了确保“private”约束成立，将创建一个新的表

CREATE TABLE extra_capabilities (
  id VARCHAR(36) NOT NULL,
  resource_type VARCHAR(255) NOT NULL,
  capability_name VARCHAR(255) NOT NULL,
  private BOOLEAN NOT NULL,

  PRIMARY key (id),
  UNIQUE INDEX (resource_type, capability_name),
);

将包含一个迁移，为所有现有功能创建 extra_capability 条目，然后更新 extra_capability 表中实现此功能的所有资源，删除 capability_name 列并将其替换为 capability_id。
规范化额外的功能意味着对现有资源的现有约束查找将需要与 extra_capabilities 表连接。

REST API 影响¶

由于给定资源类型的属性及其值集空间可能非常大，因此此功能将分解为两个端点：一个用于列出所有可能的键，另一个用于列出每个键的可能值。

GET /v1/<resource_type>/properties
- 返回资源类型支持的公共属性列表。
- 正常响应代码：200 OK
- 请求查询参数
  - detail（可选布尔值）：是否返回每个属性的可能值列表，以及属性名称。如果存在，将返回一个额外的 values 键，其中包含所有值的列表，类似于它们在返回给定属性名称值的端点中返回的方式。
- 错误响应代码
  - 404 Not Found：如果资源类型无效。
- 示例响应（对于 physical:host 资源类型）
```
[
  {
    "property": "local_gb"
  },
  {
    "property": "memory_mb"
  },
  {
    "property": "custom_capabilities.first"
  },
  {
    "property": "custom_capabilities.second"
  }
]
```
GET /v1/<resource_type>/properties/<property_name>
- 返回属性名称的有效值列表。
- 正常响应代码：200 OK
- 错误响应代码
  - 403 Forbidden：如果属性标记为私有，但使用非管理员令牌请求。
  - 404 Not Found：如果属性名称对于资源类型无效。响应主体中将返回一条指示此情况的消息。
- 示例响应（对于 physical:host 资源的 arch 属性）
```
{
  "private": false,
  "values": [
    {
      "value": "x86"
    },
    {
      "value": "arm"
    }
  ]
}
```
PATCH /v1/<resource_type>/properties/<property_name>
- 使用一些元数据更新给定的属性。当前，private 选项是唯一支持的。
- 正常响应代码：204 No Content
- 错误响应代码
  - 403 Forbidden：如果策略不允许请求用户执行 put:extra_capability。
  - 404 Not Found：如果属性名称对于资源类型无效。响应主体中将返回一条指示此情况的消息。
- 示例请求
```
{
  "private": true
}
```

安全影响¶

所有功能默认情况下都将是私有的，这应该可以降低暴露的风险。默认情况下，未来的功能也将是私有的。操作员可以通过 something 标志覆盖此行为。

如果我们想强制显式创建功能，可以提高安全性，但会牺牲操作员体验：如果我们需要在将属性附加到资源之前显式注册功能，而不是在资源更新以具有资源类型尚未看到过的属性时按需创建新功能。

通知影响¶

无

其他最终用户影响¶

Blazar CLI 客户端将更新以支持以下功能

host-capability-list：列出 physical:host 资源的所有属性
host-capability-get <name>：获取给定主机功能的所有值
host-capability-set <name> [--private|--public]：更新给定主机功能的可见性
如果我们要强制显式创建功能：host-capability-create <name> [--private|--public]：使用给定的可见性设置创建新的主机功能。

性能影响¶

将功能规范化为新表会在查找用于分配候选资源的资源时引入额外的连接，这可能会增加该操作的时间。实际上，此开销应该很低，因为功能表的空间将非常小，并且将在资源类型和功能名称上使用索引，这些将是分配选择所需的两个列。

其他部署者影响¶

为了减轻意外向用户暴露属性的风险，此新 API 默认情况下仅对操作员开放。操作员必须选择加入，允许所有用户访问 API，并在确保他们附加到资源的任何敏感功能都设置为私有之后。我们可能会在未来的版本中更改 API 的默认可见性。

[DEFAULT] capability_default_visibility：定义添加到资源的新的功能的暴露方式。默认值为 private，这意味着用户将无法枚举该属性。操作员可以将其设置为 public，以默认将功能设置为公共可见性。

开发者影响¶

无

升级影响¶

需要数据库迁移才能将新列添加到额外的功能表中。

实现¶

负责人¶

主要负责人: jasonandersonatuchicago

工作项¶

创建用于检索键/值集的 REST API 端点
创建现有额外功能的数据库迁移
更新 Blazar CLI 以支持发现资源属性
更新 Blazar CLI 以支持将资源属性更新为私有

依赖项¶

无

测试¶

将编写单元测试，如果支持这些测试的基础设施到位，则为新的 API 端点编写场景测试。

文档影响¶

需要更新 REST API 文档以包含这些新的端点。发布说明将指示新的 API 以及它授予用户的权限。

参考资料¶

IRC 讨论：http://eavesdrop.openstack.org/meetings/blazar/2020/blazar.2020-02-27-16.00.log.html

历史记录¶

可选部分，旨在每次更新规范时使用，以描述新的设计、API 或任何数据库模式更新。有助于让读者了解随着时间的推移发生了什么。

修订版¶
发布名称	描述
Ussuri	引入

资源属性发现 API