Cyborg API proposal¶
https://blueprints.launchpad.net/openstack-cyborg/+spec/cyborg-api
This spec proposes to provide the initial API design for Cyborg.
Problem description¶
Cyborg as a common management framework for dedicated devices (hardware/ software accelerators, high-speed storage, etc) needs RESTful API to expose the basic functionalities.
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.
Proposed change¶
In general we want to develop the APIs that support basic life cycle management for Cyborg.
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:
‘GET /accelerators’¶
Return a list of accelerators managed by Cyborg
Example message body of the response to the GET operation:
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}’¶
Retrieve a certain accelerator info indetified by ‘{uuid}’
Example GET Request:
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,
}
}
}
}
}
If the accelerator does not exist a 404 Not Found must be returned.
‘POST /accelerators/{uuid}’¶
Create a new accelerator
Example POST Request:
Content-type: application/json
{
"name": "IPSec Card",
"uuid": "8e45a2ea-5364-4b0d-a252-bf8becaa606e"
}
The body of the request must match the following JSONSchema document:
{
"type": "object",
"properties": {
"name": {
"type": "string"
},
"uuid": {
"type": "string",
"format": "uuid"
}
},
"required": [
"name"
]
"additionalProperties": False
}
The response body is empty. The headers include a location header pointing to the created accelerator resource:
201 Created
Location: /accelerators/8e45a2ea-5364-4b0d-a252-bf8becaa606e
A 409 Conflict response code will be returned if another accelerator exists with the provided name.
‘PUT /accelerators/{uuid}/{acc_spec}’¶
Update the spec for the accelerator identified by {uuid}.
Example:
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,
}
}
}
}
}
The returned HTTP response code will be one of the following:
200 OK if the spec is successfully updated
404 Not Found if the accelerator identified by {uuid} was not found
400 Bad Request for bad or invalid syntax
409 Conflict if another process updated the same spec.
‘PUT /accelerators/{uuid}’¶
Attach the accelerator identified by {uuid}.
Example:
PUT /accelerator/8e45a2ea-5364-4b0d-a252-bf8becaa606e
Content-type: application/json
{
"name": "IPSec Card",
"uuid": "8e45a2ea-5364-4b0d-a252-bf8becaa606e"
}
The returned HTTP response code will be one of the following:
200 OK if the accelerator is successfully attached
404 Not Found if the accelerator identified by {uuid} was not found
400 Bad Request for bad or invalid syntax
409 Conflict if another process attach the same accelerator.
‘DELETE /accelerator/{uuid}’¶
Detach the accelerator identified by {uuid}.
The body of the request and the response is empty.
The returned HTTP response code will be one of the following:
204 No Content if the request was successful and the accelerator was detached.
404 Not Found if the accelerator identified by {uuid} was not found.
409 Conflict if there exist allocations records for any of the accelerator resource that would be detached as a result of detaching the accelerator.
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.
Implementation¶
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
Dependencies¶
None.
Testing¶
Unit tests will be added to Cyborg API.
Documentation Impact¶
None
References¶
None
