Cyborg API 版本 2¶

问题描述¶

Stein 版本引入了新的设备模型和数据库 schema。这使加速器对象过时，改变了可部署对象的定义，并引入了设备的概念。这使得一些旧的 API 过时，并提出了对新 API 的需求。

其次，拟议的与 Nova 集成的方案涉及新的对象，如设备配置文件和加速器请求 (ARQs)。它们也需要新的 API。其中，设备配置文件 API 已在 3 中涵盖。

本规范将指明在 v2 中将删除哪些 v1 API，以及需要引入哪些新 API。

用例¶

作为用户，我希望创建带有附加加速器的虚拟机，删除它们并执行其他实例操作。（不包括实时迁移。）
- Cyborg 应提供设备配置文件和 ARQ 的 API，以支持与 Nova 合作的虚拟机创建、删除和其他操作的端到端工作流程。
作为操作员，我希望查询和管理加速器和设备的库存。
- Cyborg 应提供一个 API，用于根据各种属性查询设备列表。
作为具有适当授权的用户，或作为操作员，我希望启动特定设备的编程，无论是使用 FPGA 比特流，还是使用 FPGA shell 逻辑或设备固件。

提议的变更¶

微版本¶

Cyborg 应采用微版本来实现对 API 的增量向后兼容更改。这很重要，因为 Cyborg 是一个快速发展的项目，需要随着时间的推移支持新设备和功能。对于 Train 版本，将只支持一个微版本，即 2.0。

更改应与微版本规范 2 兼容。这意味着 API 的输出

GET /accelerator

必须按已更改的 API 部分中的规定进行更改。此外，一个新的 API

GET /accelerator/v2

已引入，符合该规范，如新 API 部分所述。

API 客户端可以使用以下头部来指示要使用的微版本

OpenStack-API-Version: accelerator <microversion>

如果他们不这样做，在 Train 中将假定默认微版本 2.0。

API 更改¶

以下 v1 URL 将在 v2 中不再受支持，因为加速器对象不再存在，并且可部署对象作为设备对象的一部分公开

/v1/accelerators
/v1/deployables

基于 URL 的一组新 API

/v2/device_profiles

在设备配置文件规范 (3) 中引入。

本规范引入了另一组基于 URL 的 API

/v2/accelerator_requests
/v2/devices
/v2/deployables/{uuid}

有关详细信息，请参阅新 API 部分。

备选方案¶

我们可以添加另一个 API 来启用或禁用特定设备，或特定可部署对象（资源提供者）。这留待未来版本。

数据模型影响¶

这些 API 所需的数据库更改大部分已在 Train 中完成。但是，我们需要在数据库的 deployables 表中添加一个 bitstream 字段，该字段可以作为 JSON patch 中重新编程的目标。

REST API 影响¶

已删除的 API¶

Cyborg 应在 v2 中删除加速器和可部署对象的 API。根据新定义，可部署对象将包含在新的设备 API 中。

已更改的 API¶

URL: /accelerator

METHOD: GET

角色: 管理员或任何租户

当前 JSON 响应

{
   "description": "Cyborg (previously known as Nomad) is an OpenStack
      project that aims to provide a general purpose management framework for
      acceleration resources (i.e. various types of accelerators such as
      Crypto cards, GPU, FPGA, NVMe/NOF SSDs, ODP, DPDK/SPDK and so on).",
   "name": "OpenStack Cyborg API"
}

提议的 JSON 响应

{
   "versions": [
       {
           "id": "v1",
           "links": [
               {
                   "href": "http://<ip>/accelerator/v1",
                   "rel": "self"
               }
           ],
           "version": "1.0",
           "status": "DEPRECATED"
       },
       {
           "id": "v2.0",
           "links": [
               {
                   "href": "http://<ip>/accelerator/v2",
                   "rel": "self"
               }
           ],
           "min_version": "2.0",
           "max_version": "2.0",
           "version": "2.0",
           "status": "CURRENT"
       },
   ]
}

新 API¶

URL: /accelerator/v2

METHOD: GET

角色: 管理员或任何租户

提议的 JSON 响应

{
   "id": "v2.0",
   "links": [
       {
           "href": "http://<ip>/accelerator/v2",
           "rel": "self"
       }
   ],
   "min_version": "2.0",
   "max_version": "2.0",
   "version": "2.0",
   "status": "CURRENT"
}

设备配置文件 API 已在 3 中涵盖。设备配置文件可以请求一个或多个加速器资源。每个加速器资源的请求都封装在加速器请求 (ARQ) 对象中。以下是 ARQ 的 REST API。

URL: /accelerator/v2/accelerator_requests

METHOD: GET

角色: 管理员或拥有指定实例的租户。

查询参数

实例: 所请求 ARQ 的实例的 UUID。
绑定状态: ARQ 的绑定状态。仅支持的值是
“resolved”，表示 ARQ 已成功绑定或绑定失败。将来可能支持“bound”等其他状态。

提议的 JSON 响应

{
   "arqs": [
      <arq_obj>,
      ...
   ]
}

URL: /accelerator/v2/accelerator_requests

METHOD: POST

角色: 具有 RBAC 授权的管理员或任何租户。

拟议的 JSON 请求

{
  "device_profile_name": <string>
}

操作: 为指定的设备配置文件创建 ARQ。如果设备配置文件在其所有请求组中指定了 N 个加速器资源，则将创建 N 个处于未绑定状态的 ARQ。

提议的 JSON 响应

{
   "arqs": [
      <arq_obj>,
      ...
   ]
}

URL: /accelerator/v2/accelerator_requests

方法: PATCH

角色: 管理员或拥有指定实例的租户。

拟议的 JSON 请求（RFC 6902 格式）

For binding:
{
  "$arq_uuid": [
     { "path": "/hostname", "op": "add", "value": <string> },
     { "path": "/instance_uuid",  "op": "add", "value": <uuid> },
     { "path": "/device_rp_uuid", "op": "add", "value": <uuid> }
  ],
  "$arq_uuid": [...],
  ...
}

For unbinding:
{
  "$arq_uuid": [
     { "path": "/hostname", "op": "remove" },
     { "path": "/instance_uuid",  "op": "remove" },
     { "path": "/device_rp_uuid", "op": "remove" }
  ],
  "$arq_uuid": [...],
  ...
}

操作: 绑定或解绑定

拟议的 JSON 响应: 无

URL: /accelerator/v2/accelerator_requests

METHOD: DELETE

角色: 管理员或拥有指定 ARQ 的租户。

查询参数（必需）

arqs: 一个或多个逗号分隔的 ARQ UUID 列表。

拟议的 JSON 响应: 无

URL: /accelerator/v2/devices

METHOD: GET

查询参数

提议的 JSON 响应

{
  "devices": [
     <device_obj>,
     ...
  ]
}

URL: /accelerator/v2/devices/{uuid}

方法: PATCH

角色: 具有 RBAC 授权的管理员或任何租户。

拟议的 JSON 请求（RFC 6902 格式）

{
  [
     { "path": "/firmware", "op": "add", "value": <img_uuid> },
  ]
}

操作: 更新指定设备的固件或 shell 镜像（FPGA 比特流）。请求允许路径指定符列表，以供将来扩展。: 指定设备。该请求允许一个路径指定符列表，以供将来扩展。

拟议的 JSON 响应: 无。

URL: /accelerator/v2/deployables/{uuid}

方法: PATCH

角色: 具有 RBAC 授权的管理员或任何租户。

拟议的 JSON 请求（RFC 6902 格式）

{
  [
     { "path": "/bitstream", "op": "add", "value": <img_uuid> },
  ]
}

操作: 更新指定可部署对象的 FPGA 比特流。该: 请求允许路径指定符列表，以供将来扩展。

拟议的 JSON 响应: 无。

安全影响¶

通知影响¶

无

其他最终用户影响¶

性能影响¶

无

其他部署者影响¶

开发者影响¶

实现¶

负责人¶

待定

工作项¶

依赖项¶

无

测试¶

需要编写单元测试和功能测试。

文档影响¶

Cyborg API 文档需要更新。

参考资料¶

1: Nova Cyborg 交互规范
2: 微版本和版本发现
3(1,2,3): 设备配置文件规范

历史记录¶

修订历史¶
发布名称	描述
Train	引入

Cyborg API 版本 2

Cyborg API 版本 2¶

问题描述¶

用例¶

提议的变更¶

微版本¶

API 更改¶

备选方案¶

数据模型影响¶

REST API 影响¶

已删除的 API¶

已更改的 API¶

新 API¶

安全影响¶

通知影响¶

其他最终用户影响¶

性能影响¶

其他部署者影响¶

开发者影响¶

实现¶

负责人¶

工作项¶

依赖项¶

测试¶

文档影响¶

参考资料¶

历史记录¶

cyborg-specs 0.0.1.dev123

页面内容