OpenStack Acceleration v2 APIs

This is a reference for the OpenStack Acceleration v2 API which is provided by the Cyborg project. Starting from Ussuri, Cyborg supports only Version 2 REST APIs. The Version 1 APIs were deprecated in Train and shall be removed in Ussuri.

Device Profiles

Lists, creates, shows details for, updates and deletes device profiles.

A device_profile is a named set of the user requirements for one or more accelerators. It can be viewed as a flavor for devices. Broadly it includes two things: the desired amounts of specific resource classes and the requirements that the resource provider(s) must satisfy. While the resource classes are the same as those known to Placement, some requirements would correspond to Placement traits and others to properties that Cyborg alone knows about.

GET
/v2/device_profiles

List Device Profiles

Lists UUIDs, names, groups for all device profiles.

Normal response codes: 200

Error response codes: unauthorized(401), forbidden(403)

Example response: list all device profiles

{
   "device_profiles":[
      {
         "name":"bym-1",
         "uuid":"3d03fa5b-507c-4810-a344-759e9ef4337a",
         "description": "",
         "groups":[
            {
               "resources:FPGA":"1",
               "trait:CUSTOM_FPGA_C260":"required"
            }
         ],
         "created_at": "2020-03-09 11:26:05+00:00",
         "updated_at": null,
         "links":[
            {
               "href":"http://192.168.32.217/accelerator/v2/device_profiles/3d03fa5b-507c-4810-a344-759e9ef4337a",
               "rel":"self"
            }
         ]
      },
      {
         "name":"fpga-dp1",
         "uuid":"5518a925-1c2c-49a2-a8bf-0927d9456f3e",
         "description": "",
         "groups":[
            {
               "trait:CUSTOM_CHENKE_TRAITS":"required",
               "resources:FPGA":"1",
               "accel:bitstream_id":"d5ca2f11-3108-4426-a11c-a959987565df"
            }
         ],
         "created_at": "2020-03-10 03:52:15+00:00",
         "updated_at": null,
         "links":[
            {
               "href":"http://192.168.32.217/accelerator/v2/device_profiles/5518a925-1c2c-49a2-a8bf-0927d9456f3e",
               "rel":"self"
            }
         ]
      }
   ]
}
GET
/v2/device_profiles/{device_profile_uuid}

Get One Device Profile

Gets the UUID, name, groups for one device_profile with the specified UUID.

Normal response codes: 200

Error response codes: badRequest(400), unauthorized(401), forbidden(403)

Request

Name

In

Type

Description

device_profile_uuid

path

string

The UUID of the device_profile for your accelerator request. This must be a valid UUID otherwise API will return 400.

Example response: get details of a specific device profile

{
   "device_profile":{
      "name":"fpga-dp1",
      "uuid":"5518a925-1c2c-49a2-a8bf-0927d9456f3e",
      "description": "",
      "groups":[
         {
            "trait:CUSTOM_CHENKE_TRAITS":"required",
            "resources:FPGA":"1",
            "accel:bitstream_id":"d5ca2f11-3108-4426-a11c-a959987565df"
         }
      ],
      "created_at": "2020-03-09 11:26:05+00:00",
      "updated_at": null,
      "links":[
         {
            "href":"http://192.168.32.217/accelerator/v2/device_profiles/5518a925-1c2c-49a2-a8bf-0927d9456f3e",
            "rel":"self"
         }
      ]
   }
}
POST
/v2/device_profiles

Create Device Profile

Creates a device profile. The payload should have these fields:

Normal response codes: 201

Error response codes: badRequest(400), unauthorized(401), forbidden(403), conflict(409)

Request

Name

In

Type

Description

name

body

string

The display name of a device profile.

groups

body

a list of dictionaries

This is a list of dictionaries to describe requested accelerator resource by users, where users use keys to describe the resource_classes or traits and values to indicate its quantity or property. This is intentionally similar to extra_specs in nova flavor, and uses the same keywords for resources and traits. The key-value pair can either be a resource/trait or a Cyborg property. Cyborg property is of the form “accel:<key>”: “<value>”. The valid key-value pairs can be found below.

Example post curl with resource/trait

curl -g -i -X POST $cyborg_endpoint_url/device_profiles \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "User-Agent:None" \
  -H "X-Auth-Token: yourtoken" \
  -d '[{"name": "afexample_3",
        "description": "device profile description",
        "groups": [{"resources:CUSTOM_ACCELERATOR_FPGA": "1",
                    "trait:CUSTOM_FPGA_1": "required",
                    "trait:CUSTOM_FUNCTION_ID_3AFB": "required"}]}]'

Example post curl with a cyborg property when bitstream is required

curl -g -i -X POST $cyborg_endpoint_url/device_profiles \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "User-Agent:None" \
  -H "X-Auth-Token: yourtoken" \
  -d '[{"name": "afexample_3",
        "description": "device profile description",
        "groups": [{"resources:CUSTOM_ACCELERATOR_FPGA": "1",
                    "trait:CUSTOM_FPGA_1": "required",
                    "trait:CUSTOM_FUNCTION_ID_3AFB": "required",
                    "accel:bitstream_id": "a6a12670-7014-4cff-a563-cea949b57fb3"}]}]'

Example response: create a device profile

{
   "name":"afexample_3",
   "uuid":"1a939c88-0b01-408b-bab0-4c61d3a02d71",
   "description": "",
   "groups":[
      {
         "trait:CUSTOM_FUNCTION_ID_3AFB":"required",
         "resources:CUSTOM_ACCELERATOR_FPGA":"1",
         "trait:CUSTOM_FPGA_1":"required"
      }
   ],
   "created_at": "2020-03-09 11:26:05+00:00",
   "updated_at": null,
   "links":[
      {
         "href":"http://192.168.23.76/accelerator/v2/device_profiles/1a939c88-0b01-408b-bab0-4c61d3a02d71",
         "rel":"self"
      }
   ]
}
DELETE
/v2/device_profiles/{device_profile_uuid}

Delete One Device Profile by uuid

Delete a device profile. No query parameters required.

DELETE
/v2/device_profiles?value={device_profile_name1},{device_profile_name2}

Delete Multiple Device Profiles by names

In the URL, Device profiles to be deleted should be in comma-delimited list of device profile names.

Note

Today we do not allow deletion of a device profile when it is in use by VMs, because ARQs have a foreign key on device profile table. But we copy the device profile groups into the ARQ, so this foreign key is not needed. So we can improve in Ussuri.

Response

Normal response codes: 204

There is no body content for the response of a successful DELETE query

Accelerator Requests

Lists, creates, shows details for, updates and deletes accelerator requests.

An accelerator request (ARQ) represents a request for a single accelerator to be assigned to an instance. ARQs are created in accordance with the resource_groups defined in a device_profile by the operator. The accelerator request in the user request may have N request groups, each asking for M accelerators; then N * M ARQs will be created for that accelerator request.

GET
/v2/accelerator_requests

List Accelerator Requests

Lists host_name, device_rp_uuid, instance_uuid and device_profile_group_id for all accelerator_requests.

Example response: list all accelerator requests

{
   "arqs":[
      {
         "instance_uuid":"d1e3ff56-feef-4495-8e4f-1cf6ea59ffbc",
         "hostname":"ubuntu-80",
         "uuid":"7e88a0a5-6dd9-497e-a7e0-fa2d75728a3b",
         "links":[
            {
               "href":"http://192.168.23.138/accelerator/v2/accelerator_requests/7e88a0a5-6dd9-497e-a7e0-fa2d75728a3b",
               "rel":"self"
            }
         ],
         "created_at":"2019-10-25T07:58:23+00:00",
         "device_profile_group_id":0,
         "attach_handle_type":"TEST_PCI",
         "updated_at":"2019-10-25T08:27:46+00:00",
         "state":"Bound",
         "device_rp_uuid":"03631f82-20a9-3f67-a29d-dc1abe4041bf",
         "device_profile_name":"temp-dp1",
         "attach_handle_info":{
            "device":"00",
            "bus":"0c",
            "domain":"0000",
            "function":"0"
         }
      },
      {
         "instance_uuid":null,
         "hostname":null,
         "uuid":"234c1acf-beca-47b2-9532-6bea61630936",
         "links":[
            {
               "href":"http://192.168.23.138/accelerator/v2/accelerator_requests/234c1acf-beca-47b2-9532-6bea61630936",
               "rel":"self"
            }
         ],
         "created_at":"2019-10-25T07:58:49+00:00",
         "device_profile_group_id":0,
         "attach_handle_type":"",
         "updated_at":null,
         "state":"Initial",
         "device_rp_uuid":null,
         "device_profile_name":"temp-dp1",
         "attach_handle_info":{

         }
      }
   ]
}
GET
/v2/accelerator_requests/{accelerator_request_uuid}

Get One Accelerator Request

Gets host_name, device’s_RP_UUID, instance UUID and device_profile_group_ID for one accelerator request with the specified UUID.

Request

Name

In

Type

Description

accelerator_request_uuid

path

string

The UUID of one accelerator request.

Example response: get details of a specific accelerator request

{
   "instance_uuid":null,
   "hostname":null,
   "uuid":"234c1acf-beca-47b2-9532-6bea61630936",
   "links":[
      {
         "href":"http://192.168.23.138/accelerator/v2/accelerator_requests/234c1acf-beca-47b2-9532-6bea61630936",
         "rel":"self"
      }
   ],
   "created_at":"2019-10-25T07:58:49+00:00",
   "device_profile_group_id":0,
   "attach_handle_type":"",
   "updated_at":null,
   "state":"Initial",
   "device_rp_uuid":null,
   "device_profile_name":"tmp-dp1",
   "attach_handle_info":{
   }
}
POST
/v2/accelerator_requests

Create Accelerator Requests

Creates an accelerator request. The payload should have the following field:

Request

Name

In

Type

Description

device_profile_name

path

string

The display name of a device profile.

Example post curl

curl -g -i -X POST http://192.168.23.138/accelerator/v2/accelerator_requests \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "User-Agent: None" \
  -H "X-Auth-Token: yourtoken" \
  -d '{"device_profile_name": "tmp-dp1"}'

Example response: create an accelerator request

{
   "arqs":[
      {
         "instance_uuid":null,
         "hostname":null,
         "uuid":"89ec9c4d-73b2-4aaf-9225-485945aa7162",
         "links":[
            {
               "href":"http://192.168.23.138/accelerator/v2/accelerator_requests/89ec9c4d-73b2-4aaf-9225-485945aa7162",
               "rel":"self"
            }
         ],
         "created_at":"2019-10-25T12:01:05.896464+00:00",
         "device_profile_group_id":0,
         "attach_handle_type":"",
         "updated_at":null,
         "state":"Initial",
         "device_rp_uuid":null,
         "device_profile_name":"tmp-dp1",
         "attach_handle_info":{

         }
      }
   ]
}
PATCH
/v2/accelerator_requests/{accelerator_request_uuid}

Update Accelerator Requests

The Nova compute manager calls the Cyborg API PATCH /v2/accelerator_requests to bind and unbind the ARQ with the host name, device’s RP UUID and instance UUID. This is an asynchronous call which prepares or reconfigures the device in the background.

Updates:an accelerator request. The payload should have these fields:

Request

Name

In

Type

Description

accelerator_request_uuid

path

string

The UUID of one accelerator request.

hostname

body

string

The name of the target host for bind or unbind of one accelerator request.

device_rp_uuid

body

string

UUID of the target accelerator (resource provider) for bind or unbind of one accelerator request.

instance_uuid

body

string

UUID of the target instance for bind or unbind of one accelerator request.

instance_project_id (Optional)

body

string

Project id of the target instance for bind or unbind of one accelerator request.

New in version 2.1

Example patch curl

curl -g -i -X PATCH http://192.168.23.138/accelerator/v2/accelerator_requests \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "User-Agent: None" \
  -H "X-Auth-Token: yourtoken" \
  -d '
{"89ec9c4d-73b2-4aaf-9225-485945aa7162":
    [{"op": "add", "path": "/instance_uuid",
        "value": "506220bc-18f2-4294-9b29-80267a021dc0"},
     {"op": "add", "path": "/hostname", "value": "centos-80"},
     {"op": "add", "path": "/device_rp_uuid",
        "value": "03631f82-20a9-3f67-a29d-dc1abe4042bf"}]}'

Example response: update an accelerator request

{
   "instance_uuid":"506220bc-18f2-4294-9b29-80267a021dc0",
   "hostname":"centos-80",
   "uuid":"89ec9c4d-73b2-4aaf-9225-485945aa7162",
   "links":[
      {
         "href":"http://192.168.23.138/accelerator/v2/accelerator_requests/89ec9c4d-73b2-4aaf-9225-485945aa7162",
         "rel":"self"
      }
   ],
   "created_at":"2019-10-25T12:01:05+00:00",
   "device_profile_group_id":0,
   "attach_handle_type":"TEST_PCI",
   "updated_at":"2019-10-25T12:49:49+00:00",
   "state":"Bound",
   "device_rp_uuid":"03631f82-20a9-3f67-a29d-dc1abe4042bf",
   "device_profile_name":"chenke-dp1",
   "attach_handle_info":{
      "device":"00",
      "bus":"0c",
      "domain":"0000",
      "function":"0"
   }
}
DELETE
/v2/accelerator_requests?arqs={accelerator_request_uuid}

Delete Accelerator Requests by ARQ uuid

DELETE
/v2/accelerator_requests?instance={instance_uuid}

Delete Accelerator Requests by instance uuid

Delete an accelerator request. No query parameters required.

Response

Normal response codes: 204

There is no body content for the response of a successful DELETE query

Devices

Lists, shows details for devices.

A device represent a physical card like FPGA card or GPU card.

GET
/v2/devices

List Devices

Lists UUIDs, names, type and more informations for all devices.

Normal response codes: 200

Error response codes: unauthorized(401), forbidden(403)

Example response: list all devices

{
    "devices":
    [
        {
            "uuid": "359c0990-0258-44fd-8b05-fc510ac3d022",
            "type": "FPGA",
            "vendor": "0xABCD",
            "model": "miss model info",
            "std_board_info": "{'device_id': '0xabcd', 'class': 'Fake class'}",
            "vendor_board_info": "fake_vendor_info",
            "hostname": "computenode",
            "created_at": "2020-03-13T02:26:31+00:00",
            "updated_at": null,
            "links":
            [
                {
                    "href": "http://localhost/accelerator/v2/devices/359c0990-0258-44fd-8b05-fc510ac3d022",
                    "rel": "self"
                }
            ]
        }
    ]
}
GET
/v2/devices/{device_uuid}

Get One Device

Gets the UUID, name, type and more informations for one device with the specified UUID.

Normal response codes: 200

Error response codes: badRequest(400), unauthorized(401), forbidden(403)

Request

Name

In

Type

Description

device_uuid

path

string

The UUID of the device. This must be a valid UUID otherwise API will return 400.

Example response: show details of a specific device

{
    "uuid": "359c0990-0258-44fd-8b05-fc510ac3d022",
    "type": "FPGA",
    "vendor": "0xABCD",
    "model": "miss model info",
    "std_board_info": "{'device_id': '0xabcd', 'class': 'Fake class'}",
    "vendor_board_info": "fake_vendor_info",
    "hostname": "computenode",
    "created_at": "2020-03-13T02:26:31+00:00",
    "updated_at": null,
    "links":
    [
        {
            "href": "http://localhost/accelerator/v2/devices/359c0990-0258-44fd-8b05-fc510ac3d022",
            "rel": "self"
        }
    ]
}

Deployables

Lists, shows details for deployables.

A deployables represent a logical unit of an acceleration card, such as re-configurable region of an FPGA card.

GET
/v2/deployables

List Deployables

Lists UUIDs, names, attribute list and more informations for all deployables.

Normal response codes: 200

Error response codes: unauthorized(401), forbidden(403)

Example response: list all deployables

{
   "deployables":
   [
      {
         "uuid": "29e23349-12ee-4978-963c-11484a4ae601",
         "parent_id": null,
         "root_id": null,
         "name": "computenode_FakeDevice",
         "num_accelerators": 16,
         "device_id": 1,
         "attributes_list": "[{'traits1': 'CUSTOM_FAKE_DEVICE'}, {'rc': 'FPGA'}]",
         "rp_uuid": "853f07a6-19de-3dd6-b9f6-6c782daa3f7b",
         "driver_name": "fake",
         "bitstream_id": null,
         "created_at": "2020-03-13T02:27:35+00:00",
         "updated_at": "2020-03-13T02:27:36+00:00",
         "links":
         [
            {
               "href": "http://localhost/accelerator/v2/deployables/29e23349-12ee-4978-963c-11484a4ae601",
               "rel": "self"
            },
            {
               "href": "http://localhost/accelerator/deployables/29e23349-12ee-4978-963c-11484a4ae601",
               "rel": "bookmark"
            }
         ]
      }
   ]
}
GET
/v2/deployables/{deployable_uuid}

Get One Deployable

Gets the UUID, name, attribute list and more informations for one deployable with the specified UUID.

Normal response codes: 200

Error response codes: badRequest(400), unauthorized(401), forbidden(403)

Request

Name

In

Type

Description

deployable_uuid

path

string

The UUID of the deployable. This must be a valid UUID otherwise API will return 400.

Example response: show details of a specific deployable

{
   "uuid": "29e23349-12ee-4978-963c-11484a4ae601",
   "parent_id": null,
   "root_id": null,
   "name": "computenode_FakeDevice",
   "num_accelerators": 16,
   "device_id": 1,
   "attributes_list": "[{'traits1': 'CUSTOM_FAKE_DEVICE'}, {'rc': 'FPGA'}]",
   "rp_uuid": "853f07a6-19de-3dd6-b9f6-6c782daa3f7b",
   "driver_name": "fake",
   "bitstream_id": null,
   "created_at": "2020-03-13T02:27:35+00:00",
   "updated_at": "2020-03-13T02:27:36+00:00",
   "links":
   [
      {
         "href": "http://localhost/accelerator/v2/deployables/29e23349-12ee-4978-963c-11484a4ae601",
         "rel": "self"
      },
      {
         "href": "http://localhost/accelerator/deployables/29e23349-12ee-4978-963c-11484a4ae601",
         "rel": "bookmark"
      }
   ]
}