Cyborg API proposal¶

Use Cases¶

• As a user I want to be able to spawn VM with dedicated hardware, so that I can utilize provided hardware.
• As a compute service I need to know how requested resource should be attached to the VM.
• As a scheduler service I’d like to know on which resource provider requested resource can be found.

Life Cycle Management Phases¶

For cyborg, LCM phases include typical create, retrieve, update, delete operations. One thing should be noted that deprovisioning mainly refers to detach(delete) operation which deactivate an acceleration capability but preserve the resource itself for future usage. For Cyborg, from functional point of view, the LCM includes provision, attach,update,list, and detach. There is no notion of deprovisioning for Cyborg API in a sense that we decomission or disconnect an entire accelerator device from the bus.

Difference between Provision and Attach/Detach¶

Noted that while the APIs support provisioning via CRUD operations, attach/detach are considered different:

• Provision operations (create) will involve api-> conductor->agent->driver workflow, where as attach/detach (update/delete) could be taken care of at the driver layer without the involvement of the pre-mentioned workflow. This is similar to the difference between create a volume and attach/detach a volume in Cinder.
• The attach/detach in Cyborg API will mainly involved in DB status modification.

Difference between Attach/Detach To VM and Host¶

Moreover there are also differences when we attach an accelerator to a VM or a host, similar to Cinder.

• When the attachment happens to a VM, we are expecting that Nova could call the virt driver to perform the action for the instance. In this case Nova needs to support the acc-attach and acc-detach action.
• When the attachment happens to a host, we are expecting that Cyborg could take care of the action itself via Cyborg driver. Althrough currently there is the generic driver to accomplish the job, we should consider a os-brick like standalone lib for accelerator attach/detach operations.

Alternatives¶

• For attaching an accelerator to a VM, we could let Cyborg perform the action itself, however it runs into the risk of tight-coupling with Nova of which Cyborg needs to get instance related information.
• For attaching an accelerator to a host, we could consider to use Ironic drivers however it might not bode well with the standalone accelerator rack scenarios where accelerators are not attached to server at all.

Data model impact¶

A new table in the API database will be created:

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,
);

Note that there is an ongoing discussion on nested resource provider new data structures that will impact Cyborg DB imp- lementation. For code implementation it should be aligned with resource provider db requirement as much as possible.

REST API impact¶

The API changes add resource endpoints to:

• GET a list of all the accelerators
• GET a single accelerator for a given id
• POST create a new accelerator resource
• PUT an update to an existing accelerator spec
• PUT attach an accelerator to a VM or a host
• DELETE detach an existing accelerator for a given id

The following new REST API call will be created:

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/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,
             }
         }
      }
    }
}

Content-type: application/json

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

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

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

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,
             }
          }
       }
     }
}

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

Content-type: application/json

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

Security impact¶

None

Notifications impact¶

None

Other end user impact¶

None

Performance Impact¶

None

Other deployer impact¶

None

Developer impact¶

Developers can use this REST API after it has been implemented.

Assignee(s)¶

Primary assignee:

zhipengh <huangzhipeng@huawei.com>

Work Items¶

• Implement the APIs specified in this spec
• Proposal to Nova about the new accelerator attach/detach api
• Implement the DB specified in this spec