Update api-ref: Add accelerator requests(ARQs) section

This patch added api v2 api-ref ARQs section

Depends-On: https://review.opendev.org/#/c/690539/
Change-Id: I132de9b76e1cff9e5fe6edb44ed78457f28c2092
This commit is contained in:
Yumeng Bao 2019-10-25 06:08:39 -07:00 committed by YumengBao
parent 408521a869
commit ad4ec82206
9 changed files with 313 additions and 0 deletions

115
api-ref/source/v2/arqs.inc Normal file
View File

@ -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
<http://specs.openstack.org/openstack/cyborg-specs/specs/train/approved/device-profiles.html>`_
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, devices_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, devices 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

View File

@ -10,3 +10,5 @@ in Ussuri.
.. rest_expand_all::
.. include:: device_profile.inc
.. include:: arqs.inc

View File

@ -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

View File

@ -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":{
}
}
]
}

View File

@ -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":{
}
}

View File

@ -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":{
}
}
]
}

View File

@ -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"}]}'

View File

@ -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"}'

View File

@ -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"
}
}