Cyborg 的 API 微版本¶

问题描述¶

自 Train 版本发布以来，Cyborg 已弃用 v1.0 API，并使用 v2.0 API 作为当前 API 版本。随着 Cyborg 的发展和获得新的功能，这些功能也体现在 API 变更中，我们应该支持 Cyborg 的微版本，这样不会破坏现有的基础设施。

用例¶

允许开发者以向后兼容的方式修改 Cyborg API，并动态地向 API 用户发出变更可用的信号，而无需创建新的 API 扩展。

允许开发者以非向后兼容的方式修改 Cyborg API，同时仍然支持旧的行为。REST API 的用户能够决定是否希望 Cyborg API 在每次请求的基础上以新方式或旧方式运行。部署者能够在支持开发者提供的功能的情况下，提供新的向后不兼容的功能，而不会删除对先前行为的支持。

REST API 的用户能够在每次请求的基础上决定他们想要使用的 API 版本（假设部署者支持他们想要的版本）。这意味着不升级的部署者不会破坏兼容性，并且不升级的客户端也将保持兼容。

提议的变更¶

Cyborg API 应该从客户端接收 API 版本，该版本代表它可以处理的资源列表及其 GET/POST/PATCH 属性。

Cyborg 将使用我们称之为“API 微版本”的框架，以便在保持向后兼容性的同时允许 API 变更。基本思想是用户必须显式请求将其请求视为特定版本的 API。因此，可以在不破坏明确请求它的用户的 API 的情况下，向 API 添加破坏性变更。这通过 HTTP 标头 “OpenStack-API-Version: accelerator 2.0” 来完成，这是一个从 2.0 开始的单调递增的语义版本号。

在这些情况下，我们需要一个新的微版本：1. 如果 API 的参数发生变化，我们需要添加一个新的微版本。例如，当我们向设备列表 API 添加一个新的参数来限制返回值的长度时。

2. 没有 API 的参数发生变化，但某些 API 的功能发生了变化。例如，我们已经有一个以过滤字典作为输入参数的设备列表 API，它当前支持按“attribute_A”和“attribute_B”过滤设备列表，现在我们还希望此 API 返回按“attribute_C”过滤的设备列表。在这种情况下，API 输入参数始终是过滤字典。但是 API 的功能发生了变化，因此我们也需要添加一个微版本。

如果用户在不指定版本的情况下发出请求，他们将获得在 cyborg/api/versions.py 中定义的 DEFAULT_API_VERSION。此值当前为 2.0，预计在很长一段时间内将保持不变。除非主版本发生变化并且我们弃用 V2 api 版本，否则我们不会更改此默认版本。看起来我们很少有机会更新此值。

API 的版本控制应该是一个单调递增的计数器。它将采用 X.Y 的形式，遵循以下约定

X 仅在进行影响整个 API 的重大向后不兼容的 API 变更时才会更改。也就是说，很少才递增的东西。

Y 仅在您对 API 进行任何更改时才会更改。请注意，这包括语义更改，这些更改可能不会影响输入或输出格式，甚至不会源于 API 代码层。我们不会在版本控制系统中区分向后兼容和向后不兼容的更改。但是，将在文档中明确说明哪些是向后兼容的更改，哪些是非向后兼容的更改。

版本发现¶

版本 API 将返回最小和最大微版本。这些值由客户端用于发现 API 支持的微版本。

对 / 的请求将获得所有端点的版本信息。对于 GET http://host_ip/accelerator/ 的版本响应如下所示

{
  "default_version": {
    "status": "CURRENT",
    "min_version": "2.0",
    "max_version": "2.1",
    "id": "v2.0",
    "links": [
      {
        "href": "http://host_ip/accelerator/v2",
        "rel": "self"
      }
    ]
  },
  "versions": [
    {
      "status": "CURRENT",
      "min_version": "2.0",
      "max_version": "2.1",
      "id": "v2.0",
      "links": [
        {
          "href": "http://host_ip/accelerator/v2",
          "rel": "self"
        }
      ]
    }
  ],
  "name": "OpenStack Cyborg API",
  "description": "Cyborg is the OpenStack project for lifecycle "
                 "management of hardware accelerators, such as GPUs,"
                 "FPGAs, AI chips, security accelerators, etc."
}

备选方案¶

在用户与新的 OpenStack 版本一起更新 Cyborg 时，保持原样。这可能会导致无法为遗留客户端提供请求的潜在能力。

数据模型影响¶

无

REST API 影响¶

每个 API 方法都应该用版本检查装饰器进行装饰。

有关更多 Cyborg API 详细信息，请参阅 Cyborg API 文档 3

安全影响¶

无

通知影响¶

无

其他最终用户影响¶

SDK 作者需要开始使用 OpenStack-API-Version 标头来访问新功能。只有在新版本中添加新功能这一事实将鼓励他们这样做。

python-cyborgclient 处于相同的情况，需要更新以支持新的标头才能支持新的 API 功能。

性能影响¶

无

其他部署者影响¶

无

开发者影响¶

Cyborg 的 REST API 的任何未来更改（无论是在请求中还是任何响应中）都必须导致微版本更新，并在代码中进行适当的保护。

实现¶

负责人¶

主要负责人: 王欣然(xin-ran.wang@intel.com)
其他贡献者: 斋藤彰

工作项¶

将 OpenStack-API-Version 标头推送到 API 层。
添加微版本检查装饰器。
实现包含 API 变更历史记录的 versions.py 模块。
用 versions.py 替换 api_version_request.py 并使用 microversion_parser 库。
更改 python-cyborgclient 侧面以支持 v2.0 微版本。

依赖项¶

无

测试¶

应添加适当的单元和功能测试。

文档影响¶

需要文档来记录微版本历史记录。
需要一份文档来解释什么是向后兼容/不兼容，什么是 Cyborg 的微版本，如何发现版本以及如何与 cyborgclient 交互。

参考资料¶

1: 微版本规范
2: Cinder 微版本规范
3: Cyborg API 文档

历史记录¶

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

Cyborg API 微版本