Cyborg API 提案

https://blueprints.launchpad.net/openstack-cyborg/+spec/cyborg-api

本规范提出为 Cyborg 提供初始 API 设计。

问题描述

Cyborg 作为专用设备（硬件/软件加速器、高速存储等）的通用管理框架，需要 RESTful API 来暴露基本功能。

用例

• 作为用户，我希望能够使用专用硬件启动虚拟机，以便利用提供的硬件。

• 作为计算服务，我需要知道如何将请求的资源附加到虚拟机。

• 作为调度服务，我希望知道请求的资源可以在哪个资源提供商处找到。

提议的变更

总的来说，我们希望开发支持 Cyborg 基本生命周期管理的 API。

生命周期管理阶段

对于 Cyborg，LCM 阶段包括典型的创建、检索、更新、删除操作。需要注意的是，废弃主要指的是分离（删除）操作，它会停用加速能力，但保留资源本身以供将来使用。从功能角度来看，Cyborg 的 LCM 包括配置、附加、更新、列表和分离。在 Cyborg API 中没有废弃的概念，因为我们不会从总线上移除或断开整个加速器设备。

配置和附加/分离之间的区别

请注意，虽然 API 支持通过 CRUD 操作进行配置，但附加/分离被认为是不同的

• 配置操作（创建）将涉及 api->conductor->agent->driver 工作流，而附加/分离（更新/删除）可以在驱动程序层处理，而无需涉及上述工作流。这类似于 Cinder 中创建卷和附加/分离卷之间的区别。

• Cyborg API 中的附加/分离主要涉及数据库状态修改。

附加/分离到虚拟机和主机之间的区别

此外，当我们把加速器附加到虚拟机或主机时，也存在差异，类似于 Cinder。

• 当附加操作发生在虚拟机上时，我们期望 Nova 可以调用 virt 驱动程序来为实例执行该操作。在这种情况下，Nova 需要支持 acc-attach 和 acc-detach 操作。

• 当附加操作发生在主机上时，我们期望 Cyborg 可以通过 Cyborg 驱动程序自行处理该操作。虽然目前存在通用驱动程序来完成这项工作，但我们应该考虑类似于 os-brick 的独立库，用于加速器附加/分离操作。

备选方案

• 对于将加速器附加到虚拟机，我们可以让 Cyborg 自身执行该操作，但是这会面临与 Nova 紧密耦合的风险，Cyborg 需要获取与实例相关的信息。

• 对于将加速器附加到主机，我们可以考虑使用 Ironic 驱动程序，但是这可能与独立加速器机架场景不符，在这些场景中，加速器根本没有附加到服务器。

数据模型影响

将在 API 数据库中创建一个新表

CREATE TABLE accelerators (
    accelerator_id INT NOT NULL,
    device_type STRING NOT NULL,
    acc_type STRING NOT NULL,
    acc_capability STRING NOT NULL,
    vendor_id STRING,
    product_id STRING,
    remotable INT,
);

请注意，目前正在讨论嵌套资源提供商新的数据结构，这将影响 Cyborg DB 实现。对于代码实现，应尽可能与资源提供商数据库要求保持一致。

REST API 影响

API 更改将向以下位置添加资源端点

• GET 获取所有加速器的列表

• GET 获取给定 ID 的单个加速器

• POST 创建一个新的加速器资源

• PUT 更新现有的加速器规范

• PUT 将加速器附加到虚拟机或主机

• DELETE 分离给定 ID 的现有加速器

将创建以下新的 REST API 调用

‘GET /accelerators’

返回 Cyborg 管理的加速器列表

响应 GET 操作的消息体示例

200 OK
Content-Type: application/json

{
   "accelerator":[
    {
      "uuid":"8e45a2ea-5364-4b0d-a252-bf8becaa606e",
      "acc_specs":
      {
         "remote":0,
         "num":1,
         "device_type":"CRYPTO"
         "acc_capability":
         {
            "num":2
            "ipsec":
            {
               "aes":
               {
                  "3des":50,
                  "num":1,
               }
            }
         }
       }
     },
     {
       "uuid":"eaaf1c04-ced2-40e4-89a2-87edded06d64",
       "acc_specs":
       {
          "remote":0,
          "num":1,
          "device_type":"CRYPTO"
          "acc_capability":
          {
             "num":2
             "ipsec":
             {
                "aes":
                {
                   "3des":40,
                   "num":1,
                }
             }
          }
        }
      }
   ]
}

‘GET /accelerators/{uuid}’

检索由‘{uuid}’标识的特定加速器信息

GET 请求示例

GET /accelerators/8e45a2ea-5364-4b0d-a252-bf8becaa606e

200 OK
Content-Type: application/json

{
   "uuid":"8e45a2ea-5364-4b0d-a252-bf8becaa606e",
   "acc_specs":{
      "remote":0,
      "num":1,
      "device_type":"CRYPTO"
      "acc_capability":{
         "num":2
         "ipsec":{
             "aes":{
               "3des":50,
               "num":1,
             }
         }
      }
    }
}

如果加速器不存在，必须返回 404 Not Found。

‘POST /accelerators/{uuid}’

创建一个新的加速器

POST 请求示例

Content-type: application/json

{
    "name": "IPSec Card",
    "uuid": "8e45a2ea-5364-4b0d-a252-bf8becaa606e"
}

请求体必须符合以下 JSONSchema 文档

{
    "type": "object",
    "properties": {
        "name": {
            "type": "string"
        },
        "uuid": {
            "type": "string",
            "format": "uuid"
        }
    },
    "required": [
        "name"
    ]
    "additionalProperties": False
}

响应体为空。标头包括一个 location 标头，指向创建的加速器资源

201 Created
Location: /accelerators/8e45a2ea-5364-4b0d-a252-bf8becaa606e

如果已经存在具有提供的名称的另一个加速器，将返回 409 Conflict 响应代码。

‘PUT /accelerators/{uuid}/{acc_spec}’

更新由 {uuid} 标识的加速器的规范。

示例

PUT /accelerator/8e45a2ea-5364-4b0d-a252-bf8becaa606e

Content-type: application/json

{
    "acc_specs":{
       "remote":0,
       "num":1,
       "device_type":"CRYPTO"
       "acc_capability":{
          "num":2
          "ipsec":{
             "aes":{
               "3des":50,
               "num":1,
             }
          }
       }
     }
}

返回的 HTTP 响应代码将是以下之一

• 200 OK 如果规范成功更新

• 404 Not Found 如果未找到由 {uuid} 标识的加速器

• 400 Bad Request 对于错误的或无效的语法

• 409 Conflict 如果另一个进程更新了相同的规范。

‘PUT /accelerators/{uuid}’

附加由 {uuid} 标识的加速器。

示例

PUT /accelerator/8e45a2ea-5364-4b0d-a252-bf8becaa606e

Content-type: application/json

{
    "name": "IPSec Card",
    "uuid": "8e45a2ea-5364-4b0d-a252-bf8becaa606e"
}

返回的 HTTP 响应代码将是以下之一

• 200 OK 如果加速器成功附加

• 404 Not Found 如果未找到由 {uuid} 标识的加速器

• 400 Bad Request 对于错误的或无效的语法

• 409 Conflict 如果另一个进程附加了相同的加速器。

‘DELETE /accelerator/{uuid}’

分离由 {uuid} 标识的加速器。

请求体和响应体为空。

返回的 HTTP 响应代码将是以下之一

• 204 No Content 如果请求成功并且加速器已分离。

• 404 Not Found 如果未找到由 {uuid} 标识的加速器。

• 409 Conflict 如果存在任何将被分离的加速器资源的分配记录，从而导致分离加速器。

安全影响

无

通知影响

无

其他最终用户影响

无

性能影响

无

其他部署者影响

无

开发者影响

开发人员可以在实现后使用此 REST API。

实现

负责人

主要负责人

zhipengh <huangzhipeng@huawei.com>

工作项

• 实现本规范中指定的 API

• 关于新的加速器附加/分离 api 的 Nova 提案

• 实现本规范中指定的 DB

依赖项

无。

测试

• 将向 Cyborg API 添加单元测试。

文档影响

无

参考资料

无

历史记录

修订版

发布	描述
Pike	引入