diff --git a/api-ref/source/v1/deployables.inc b/api-ref/source/v1/deployables.inc index e69de29b..311d7da2 100644 --- a/api-ref/source/v1/deployables.inc +++ b/api-ref/source/v1/deployables.inc @@ -0,0 +1,119 @@ +.. -*- rst -*- +.. needs:body_verification + +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". + +List Deployables +---------------- + +.. rest_method:: GET /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** + +.. literalinclude:: ../../../doc/api_samples/deployables/deployables-list-resp.json + :language: javascript + +Get One Deployable +------------------ + +.. rest_method:: GET /deployables/uuid + +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** + +.. literalinclude:: ../../../doc/api_samples/deployables/deployables-getone-resp.json + +Create Deployable +----------------- + +.. rest_method:: POST /deployables + +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** + +.. literalinclude:: ../../../doc/api_samples/deployables/deployable-post-curl.json + +**Example response: create a deployable** + +.. literalinclude:: ../../../doc/api_samples/deployables/deployable-create-resp.json + +Update Deployable +----------------- + +.. rest_method:: PATCH /deployables/uuid + +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** + +.. literalinclude:: ../../../doc/api_samples/deployables/deployable-patch-curl.json + +**Example response: update a deployable** + +.. literalinclude:: ../../../doc/api_samples/deployables/deployable-update-resp.json + +Delete Deployable +----------------- + +.. rest_method:: DELETE /deployables/uuid + +Delete a deployable. No query parameters required. + +Response will be like the following: + + .. code-block:: bash + + 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 diff --git a/api-ref/source/v1/index.rst b/api-ref/source/v1/index.rst index c99dcb73..1f782e23 100644 --- a/api-ref/source/v1/index.rst +++ b/api-ref/source/v1/index.rst @@ -3,7 +3,7 @@ OpenStack Acceleration v1 APIs ============================== v1 APIs -####### +======= This is a reference for the OpenStack Acceleration v1 API which is provided by the Cyborg project. @@ -13,7 +13,7 @@ the Cyborg project. .. include:: deployables.inc Deprecated v1 APIs -################## +================== This section contains references for v1 APIs which are deprecated and usually limited to some maximum microversion. diff --git a/doc/api_samples/deployables/deployable-create-resp.json b/doc/api_samples/deployables/deployable-create-resp.json new file mode 100644 index 00000000..a77d5fa7 --- /dev/null +++ b/doc/api_samples/deployables/deployable-create-resp.json @@ -0,0 +1,36 @@ +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" +} diff --git a/doc/api_samples/deployables/deployable-patch-curl.json b/doc/api_samples/deployables/deployable-patch-curl.json new file mode 100644 index 00000000..0a4b1192 --- /dev/null +++ b/doc/api_samples/deployables/deployable-patch-curl.json @@ -0,0 +1,10 @@ +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"}]' diff --git a/doc/api_samples/deployables/deployable-post-curl.json b/doc/api_samples/deployables/deployable-post-curl.json new file mode 100644 index 00000000..adb0b47f --- /dev/null +++ b/doc/api_samples/deployables/deployable-post-curl.json @@ -0,0 +1,26 @@ +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 +}' diff --git a/doc/api_samples/deployables/deployable-update-resp.json b/doc/api_samples/deployables/deployable-update-resp.json new file mode 100644 index 00000000..b07138cf --- /dev/null +++ b/doc/api_samples/deployables/deployable-update-resp.json @@ -0,0 +1,72 @@ +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 +} diff --git a/doc/api_samples/deployables/deployables-getone-resp.json b/doc/api_samples/deployables/deployables-getone-resp.json new file mode 100644 index 00000000..3f77b607 --- /dev/null +++ b/doc/api_samples/deployables/deployables-getone-resp.json @@ -0,0 +1,35 @@ +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" +} diff --git a/doc/api_samples/deployables/deployables-list-resp.json b/doc/api_samples/deployables/deployables-list-resp.json new file mode 100644 index 00000000..e742696f --- /dev/null +++ b/doc/api_samples/deployables/deployables-list-resp.json @@ -0,0 +1,62 @@ +{ + "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 + } + ] +}