OpenStack Acceleration v1 APIs

v1 APIs

This is a reference for the OpenStack Acceleration v1 API which is provided by the Cyborg project.

Deployables

Lists, creates, shows details for, updates and deletes deployables.

A deployable is a component of a device that contains accelerators. (An accelerator is a hardware resource that offload computation; it is the smallest unit within a device that can be assigned to a VM.)

Note

In the following example url requests $cyborg_endpoint_url can be different depending on how cyborg-api service is running. If cyborg-api service is running as a python process, use “http://localhost:6666/v1”, otherwise if cyborg-api is running as a WSGI application: “https://docs.openstack.org/cyborg/latest/admin/config-wsgi.html”, use “http://localhost/accelerator/v1”.

GET
/deployables

List Deployables

Lists UUIDs, names, number of accelerators, device_ids and root_ids, parent_ids for all deployables.

Supported query parameters:

  • limit: Optional, to determinate maximum number of accelerators to return.
  • marker: Optional, to display a list of accelerators after this marker.
  • sort_key: Optional, to sort the returned deployables list by this
    specified key value.
  • sort_dir: Optional, to return the deployables list with sort direction.

Example response: list deployables

{
   "deployables":[
      {
         "instance_uuid":null,
         "assignable":false,
         "vendor":"ZTE",
         "parent_uuid":null,
         "links":[
            {
               "href":"http://192.168.23.76/v1/deployables/9044a4ae-a9d7-4554-97e4-fc63626a4b08",
               "rel":"self"
            },
            {
               "href":"http://192.168.23.76/deployables/9044a4ae-a9d7-4554-97e4-fc63626a4b08",
               "rel":"bookmark"
            }
         ],
         "updated_at":null,
         "interface_type":"pci",
         "uuid":"9044a4ae-a9d7-4554-97e4-fc63626a4b08",
         "name":"zte-hpts-1",
         "created_at":null,
         "host":"localhost",
         "version":"1",
         "board":"acc_board_type",
         "address":"06.00.1",
         "attributes_list":"[]",
         "type":"pf",
         "availability":"released",
         "root_uuid":null
      },
      {
         "instance_uuid":null,
         "assignable":false,
         "vendor":"ZTE",
         "parent_uuid":null,
         "links":[
            {
               "href":"http://192.168.23.76/v1/deployables/155b5100-eaf3-4441-8694-ae17c82eddcb",
               "rel":"self"
            },
            {
               "href":"http://192.168.23.76/deployables/155b5100-eaf3-4441-8694-ae17c82eddcb",
               "rel":"bookmark"
            }
         ],
         "updated_at":null,
         "interface_type":"pci",
         "uuid":"155b5100-eaf3-4441-8694-ae17c82eddcb",
         "name":"zte-hpts-2",
         "created_at":null,
         "host":"localhost",
         "version":"1",
         "board":"acc_board_type",
         "address":"06.00.1",
         "attributes_list":"[]",
         "type":"pf",
         "availability":"released",
         "root_uuid":null
      }
   ]
}
GET
/deployables/uuid

Get One Deployable

Gets the UUID, name, number of accelerators and other fields for one deployable with the specified UUID.

Gets a deployable. The payload should have these fields:

  • uuid: UUID

Example response: get details of a specific deployable

HTTP/1.1 200 OK
Content-Length: 670
Content-Type: application/json
X-Openstack-Request-Id: req-d1afc394-03d0-4768-8270-760e0ed5c5e9
Date: Wed, 27 Mar 2019 02:09:29 GMT

{  
   "instance_uuid":null,
   "assignable":false,
   "vendor":"ZTE",
   "parent_uuid":null,
   "links":[  
      {  
         "href":"http://192.168.23.76:6666/v1/deployables/6a477822-4598-4a1a-ae6f-c4f9d370e4aa",
         "rel":"self"
      },
      {  
         "href":"http://192.168.23.76:6666/deployables/6a477822-4598-4a1a-ae6f-c4f9d370e4aa",
         "rel":"bookmark"
      }
   ],
   "updated_at":null,
   "interface_type":"pci",
   "uuid":"6a477822-4598-4a1a-ae6f-c4f9d370e4aa",
   "name":"zte-hpts-6",
   "created_at":"2019-03-27T01:38:14+00:00",
   "host":"localhost",
   "version":"1",
   "board":"acc_board_type",
   "address":"06.00.1",
   "attributes_list":"[]",
   "type":"pf",
   "availability":"released",
   "root_uuid":"6a477822-4598-4a1a-ae6f-c4f9d370e4aa"
}
POST
/deployables

Create Deployable

Creates a deployable. The payload should have these fields:

  • uuid: UUID
  • name: string
  • num_accelerators: integer
  • address: string
  • interface_type: string
  • assignable: boolean
  • availability: string
  • accelerator_id: integer

Example post curl

curl -g -i -X POST $cyborg_endpoint_url/deployables \
  -H "Accept: application/json" -H "Content-Type: application/json" \
  -H "OpenStack-API-Version: container-infra latest" \
  -H "User-Agent:None" \
  -H "X-Auth-Token: yourtoken" \
  -d '
{  
   "instance_uuid":null,
   "assignable":false,
   "vendor":"ZTE",
   "parent_uuid":null,
   "updated_at":null,
   "interface_type":"pci",
   "uuid":"6a477822-4598-4a1a-ae6f-c4f9d370e4aa",
   "name":"zte-hpts-6",
   "created_at":null,
   "host":"localhost",
   "version":"1",
   "board":"acc_board_type",
   "address":"06.00.1",
   "attributes_list":"[]",
   "type":"pf",
   "availability":"released",
   "root_uuid":null,
   "accelerator_id":2
}'

Example response: create a deployable

HTTP/1.1 201 Created
Location: http://192.168.23.76:6666/v1/deployables/6a477822-4598-4a1a-ae6f-c4f9d370e4aa
Content-Length: 670
Content-Type: application/json
X-Openstack-Request-Id: req-055ffe9c-3916-4b27-8a09-d24a8370ec4c
Date: Wed, 27 Mar 2019 01:38:14 GMT

{ 
   "instance_uuid":null,
   "assignable":false,
   "vendor":"ZTE",
   "parent_uuid":null,
   "links":[
      {
         "href":"http://192.168.23.76:6666/v1/deployables/6a477822-4598-4a1a-ae6f-c4f9d370e4aa",
         "rel":"self"
      },
      {
         "href":"http://192.168.23.76:6666/deployables/6a477822-4598-4a1a-ae6f-c4f9d370e4aa",
         "rel":"bookmark"
      }
   ],
   "updated_at":null,
   "interface_type":"pci",
   "uuid":"6a477822-4598-4a1a-ae6f-c4f9d370e4aa",
   "name":"zte-hpts-6",
   "created_at":"2019-03-27T01:38:14+00:00",
   "host":"localhost",
   "version":"1",
   "board":"acc_board_type",
   "address":"06.00.1",
   "attributes_list":"[]",
   "type":"pf",
   "availability":"released",
   "root_uuid":"6a477822-4598-4a1a-ae6f-c4f9d370e4aa"
}
PATCH
/deployables/uuid

Update Deployable

Update a deployable. The payload should be a RFC 6902-compliant JSON patch, FYR:”http://jsonpatch.com/”. The patch should have these fields:

  • uuid: UUID

Other fields are optional.

Example patch curl

curl -g -i -X PATCH $cyborg_endpoint_url/deployables/uuid \
  -H "Accept: applicatiapplication/json" \
  -H "OpenStack-API-Version: container-infra latest" \
  -H "User-Agent: None" \
  -H "X-Auth-Token: your_token" \
  -d '
[{"op": "replace", "path": "/assignable", "value": "false"},
 {"op": "remove", "path": "/root_uuid"}, 
 {"op": "add", "path": "/parent_uuid", 
      "value": "155b5100-eaf3-4441-8694-ae17c82eddcb"}]'

Example response: update a deployable

Before patch:

{
   "instance_uuid":null,
   "assignable":true,
   "vendor":"ZTE",
   "parent_uuid":null,
   "links":[
      {
         "href":"http://192.168.23.76/v1/deployables/f1ca30c2-f28b-4b6c-b1f6-f46e4adaa63a",
         "rel":"self"
      },
      {
         "href":"http://192.168.23.76/deployables/f1ca30c2-f28b-4b6c-b1f6-f46e4adaa63a",
         "rel":"bookmark"
      }
   ],
   "updated_at":"2019-03-30T09:40:21+00:00",
   "interface_type":"pci",
   "uuid":"f1ca30c2-f28b-4b6c-b1f6-f46e4adaa63a",
   "name":"zte-hpts-6",
   "created_at":"2019-03-30T08:39:47+00:00",
   "host":"localhost",
   "version":"1",
   "board":"acc_board_type",
   "address":"06.00.1",
   "attributes_list":"[]",
   "type":"pf",
   "availability":"released",
   "root_uuid":"f1ca30c2-f28b-4b6c-b1f6-f46e4adaa63a"
}

After patch:

HTTP/1.1 200 OK
Date: Sat, 30 Mar 2019 09:40:21 GMT
Server: Apache/2.4.29 (Ubuntu)
Content-Length: 683
Content-Type: application/json
x-openstack-request-id: req-f58854f5-bf29-4380-84c1-21b70e732d0c
Connection: close

{
   "instance_uuid":null,
   "assignable":false,
   "vendor":"ZTE",
   "parent_uuid":"155b5100-eaf3-4441-8694-ae17c82eddcb",
   "links":[
      {
         "href":"http://192.168.23.76/v1/deployables/f1ca30c2-f28b-4b6c-b1f6
             -f46e4adaa63a",
         "rel":"self"
      },
      {
         "href":"http://192.168.23.76/deployables/f1ca30c2-f28b-4b6c-b1f6-f46e4adaa63a",
         "rel":"bookmark"
      }
   ],
   "updated_at":"2019-03-30T09:40:21+00:00",
   "interface_type":"pci",
   "uuid":"f1ca30c2-f28b-4b6c-b1f6-f46e4adaa63a",
   "name":"zte-hpts-6",
   "created_at":"2019-03-30T08:39:47+00:00",
   "host":"localhost",
   "version":"1",
   "board":"acc_board_type",
   "address":"06.00.1",
   "attributes_list":"[]",
   "type":"pf",
   "availability":"released",
   "root_uuid":null
}
DELETE
/deployables/uuid

Delete Deployable

Delete a deployable. No query parameters required.

Response will be like the following:

HTTP/1.1 204 No Content
Date: Sat, 30 Mar 2019 09:51:49 GMT
Server: Apache/2.4.29 (Ubuntu)
x-openstack-request-id: req-46603a01-f04d-40b6-922f-2f2ec1201725
Connection: close

Deprecated v1 APIs

This section contains references for v1 APIs which are deprecated and usually limited to some maximum microversion.