Cyborg API 版本 2¶

问题描述¶

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

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

本规范将说明 v1 API 在 v2 中将被弃用哪些，以及需要引入哪些新的 API。

用例¶

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

提议的变更¶

微版本¶

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

这些更改应与微版本规范 1 兼容。这意味着 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

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

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

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

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

备选方案¶

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

数据模型影响¶

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

此外，我们需要在数据库的 device 表中添加一个 status 字段，该字段可以指示设备是启用还是禁用。

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 在 2 中涵盖。设备配置文件可以请求一个或多个加速器资源。每个加速器资源的请求封装在加速器请求 (ARQ) 对象中。以下是 ARQ 的 REST API。

URL: /accelerator/v2/accelerator_requests

METHOD: GET

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

查询参数

instance: 请求的 ARQ 所属实例的 UUID。
bind_state: 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

查询参数: * hostname: 设备所在的计算节点的 hostname。

type: 设备的类型。例如，要获取所有 FPGA 设备，请将 “FPGA” 添加为查询参数。
vendor: 设备的供应商 ID。例如，要获取所有 Intel 设备，请将 “0x8086” 添加为查询参数。

提议的 JSON 响应

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

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

METHOD: GET

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

提议的 JSON 响应

{
    "vendor": "0x8086",
    "uuid": "1c6c9033-560d-4a7a-bb8e-94455d1e7825",
    "links":
    [
        {"href": "http://10.238.145.73/accelerator/v2/devices/1c6c9033-560d-4a7a-bb8e-94455d1e7825",
         "rel": "self"
         }
    ],
    "created_at": "2019-11-12T07:38:55+00:00",
    "hostname": "host1",
    "updated_at": null,
    "vendor_board_info": "fake_vendor_info",
    "model": "fake_model_info",
    "type": "FPGA",
    "id": 2,
    "std_board_info": "{"class": "Fake class", "device_id": "0x09c4"}
}

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

方法: PATCH

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

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

{
  [
     { "path": "/status", "op": "replace", "value": "enabled", "reason": "reason(optional)" },
  ]
}

操作: 将设备状态更新为 enabled。此请求将调用 placement API，将该设备下的所有资源提供者设置为可用。操作员可以选择附加操作原因。

提议的 JSON 响应: 无。

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

方法: PATCH

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

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

{
  [
     { "path": "/status", "op": "replace", "value": "disabled", "reason": "reason(optional)" },
  ]
}

操作: 将设备状态更新为 disabled。此请求将调用 placement API，更新该设备下所有资源提供者的库存的 reserved 字段，从而从最终用户的角度禁用该设备。操作员可以选择附加操作原因。

提议的 JSON 响应: 无。

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

方法: PATCH

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

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

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

操作: 更新指定可部署对象的 FPGA 位流。该: 请求允许使用路径说明符列表，以便将来扩展。

提议的 JSON 响应: 无。

安全影响¶

无

通知影响¶

无

其他最终用户影响¶

无

性能影响¶

无

其他部署者影响¶

无

开发者影响¶

无

实现¶

负责人¶

待定

工作项¶

依赖项¶

无

测试¶

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

文档影响¶

Cyborg API 文档需要更新。

参考资料¶

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

历史记录¶

修订版¶
发布名称	描述
Train	引入
Ussuri	重新提出

Cyborg API 版本 2

Cyborg API 版本 2¶

问题描述¶

用例¶

提议的变更¶

微版本¶

API 更改¶

备选方案¶

数据模型影响¶

REST API 影响¶

已删除的 API¶

更改的 API¶

新的 API¶

安全影响¶

通知影响¶

其他最终用户影响¶

性能影响¶

其他部署者影响¶

开发者影响¶

实现¶

负责人¶

工作项¶

依赖项¶

测试¶

文档影响¶

参考资料¶

历史记录¶

cyborg-specs 0.0.1.dev123

页面内容