diff --git a/api-ref/source/v2/arqs.inc b/api-ref/source/v2/arqs.inc new file mode 100644 index 00000000..24cd8694 --- /dev/null +++ b/api-ref/source/v2/arqs.inc @@ -0,0 +1,115 @@ +.. -*- rst -*- +.. needs:body_verification + +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. + +List Accelerator Requests +------------------------- + +.. rest_method:: GET /v2/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** + +.. literalinclude:: ../../../doc/api_samples/accelerator_requests/accelerator_requests-list-resp.json + :language: javascript + +Get One Accelerator Request +--------------------------- + +.. rest_method:: GET /v2/accelerator_requests/{accelerator_request_uuid} + +Gets host_name, device’s_RP_UUID, instance UUID and device_profile_group_ID +for one accelerator request with the specified UUID. + +Request +======= +.. rest_parameters:: parameters.yaml + + - accelerator_request_uuid: accelerator_request_uuid + +**Example response: get details of a specific accelerator request** + +.. literalinclude:: ../../../doc/api_samples/accelerator_requests/accelerator_requests-getone-resp.json + +Create Accelerator Requests +--------------------------- + +.. rest_method:: POST /v2/accelerator_requests + +Creates an accelerator request. The payload should have the following field: + +Request +======= +.. rest_parameters:: parameters.yaml + + - device_profile_name: device_profile_name + +**Example post curl** + +.. literalinclude:: ../../../doc/api_samples/accelerator_requests/accelerator_requests-post-curl.json + +**Example response: create an accelerator request** + +.. literalinclude:: ../../../doc/api_samples/accelerator_requests/accelerator_requests-create-resp.json + +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. + +.. rest_method:: PATCH /v2/accelerator_requests/{accelerator_request_uuid} + +Updates:an accelerator request. The payload should have these fields: + +Request +======= +.. rest_parameters:: parameters.yaml + + - accelerator_request_uuid: accelerator_request_uuid + - hostname: hostname_bind_unbind_req + - device_rp_uuid: device_rp_uuid_bind_unbind_req + - instance_uuid: instance_uuid_bind_unbind_req + +**Example patch curl** + +.. literalinclude:: ../../../doc/api_samples/accelerator_requests/accelerator_requests-patch-curl.json + +**Example response: update an accelerator request** + +.. literalinclude:: ../../../doc/api_samples/accelerator_requests/accelerator_requests-update-resp.json + +Delete Accelerator Requests by ARQ uuid +--------------------------------------- + +.. rest_method:: DELETE /v2/accelerator_requests?arqs={accelerator_request_uuid} + +Delete Accelerator Requests by instance uuid +-------------------------------------------- + +.. rest_method:: DELETE /v2/accelerator_requests?instance={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 diff --git a/api-ref/source/v2/index.rst b/api-ref/source/v2/index.rst index 6ac07769..72d9a441 100644 --- a/api-ref/source/v2/index.rst +++ b/api-ref/source/v2/index.rst @@ -10,3 +10,5 @@ in Ussuri. .. rest_expand_all:: .. include:: device_profile.inc + +.. include:: arqs.inc diff --git a/api-ref/source/v2/parameters.yaml b/api-ref/source/v2/parameters.yaml index fef26d94..e4b7b1bb 100644 --- a/api-ref/source/v2/parameters.yaml +++ b/api-ref/source/v2/parameters.yaml @@ -1,3 +1,16 @@ +# variables in path +accelerator_request_uuid: + description: | + The UUID of one accelerator request. + in: path + required: true + type: string +device_profile_name: + description: | + The display name of a device profile. + in: path + required: true + type: string device_profile_uuid: description: | The UUID of the device_profile for your accelerator request. @@ -5,6 +18,7 @@ device_profile_uuid: in: path required: true type: string +# variables in body device_prof_groups_req: description: | This is a list of dictionaries to describe requested accelerator resource @@ -24,3 +38,22 @@ device_prof_name_req: in: body required: true type: string +device_rp_uuid_bind_unbind_req: + description: | + UUID of the target accelerator (resource provider) for bind or unbind of + one accelerator request. + in: body + required: true + type: string +hostname_bind_unbind_req: + description: | + The name of the target host for bind or unbind of one accelerator request. + in: body + required: true + type: string +instance_uuid_bind_unbind_req: + description: | + UUID of the target instance for bind or unbind of one accelerator request. + in: body + required: true + type: string diff --git a/doc/api_samples/accelerator_requests/accelerator_requests-create-resp.json b/doc/api_samples/accelerator_requests/accelerator_requests-create-resp.json new file mode 100644 index 00000000..cd4b99b2 --- /dev/null +++ b/doc/api_samples/accelerator_requests/accelerator_requests-create-resp.json @@ -0,0 +1,25 @@ +{ + "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":{ + + } + } + ] +} diff --git a/doc/api_samples/accelerator_requests/accelerator_requests-getone-resp.json b/doc/api_samples/accelerator_requests/accelerator_requests-getone-resp.json new file mode 100644 index 00000000..4694c4f6 --- /dev/null +++ b/doc/api_samples/accelerator_requests/accelerator_requests-getone-resp.json @@ -0,0 +1,20 @@ +{ + "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":{ + } +} diff --git a/doc/api_samples/accelerator_requests/accelerator_requests-list-resp.json b/doc/api_samples/accelerator_requests/accelerator_requests-list-resp.json new file mode 100644 index 00000000..c39b2d65 --- /dev/null +++ b/doc/api_samples/accelerator_requests/accelerator_requests-list-resp.json @@ -0,0 +1,49 @@ +{ + "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":{ + + } + } + ] +} diff --git a/doc/api_samples/accelerator_requests/accelerator_requests-patch-curl.json b/doc/api_samples/accelerator_requests/accelerator_requests-patch-curl.json new file mode 100644 index 00000000..6e117f0c --- /dev/null +++ b/doc/api_samples/accelerator_requests/accelerator_requests-patch-curl.json @@ -0,0 +1,12 @@ +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"}]}' diff --git a/doc/api_samples/accelerator_requests/accelerator_requests-post-curl.json b/doc/api_samples/accelerator_requests/accelerator_requests-post-curl.json new file mode 100644 index 00000000..a1573b13 --- /dev/null +++ b/doc/api_samples/accelerator_requests/accelerator_requests-post-curl.json @@ -0,0 +1,6 @@ +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"}' diff --git a/doc/api_samples/accelerator_requests/accelerator_requests-update-resp.json b/doc/api_samples/accelerator_requests/accelerator_requests-update-resp.json new file mode 100644 index 00000000..fb8fec7f --- /dev/null +++ b/doc/api_samples/accelerator_requests/accelerator_requests-update-resp.json @@ -0,0 +1,51 @@ +Before PATCH + +{ + "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+00:00", + "device_profile_group_id":0, + "attach_handle_type":"", + "updated_at":null, + "state":"Initial", + "device_rp_uuid":null, + "device_profile_name":"chenke-dp1", + "attach_handle_info":{ + + } +} + +After PATCH + +{ + "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" + } +} +