Update api-ref: deprecate v1 add v2 device_profile section
This patch:
1. remove api v1 section since The Version 1 APIs were deprecated in
Train and shall be removed in Ussuri.
2. add api v2 device_profile section
3. other V2 apis will be added in following patches
Change-Id: I79e8adf26238a5cc6664bbef94444c59b69475fc
This commit is contained in:
Yumeng Bao
@@ -8,4 +8,4 @@ the Cyborg project.
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
v1/index
|
||||
v2/index
|
||||
|
||||
@@ -1,119 +0,0 @@
|
||||
.. -*- 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
|
||||
@@ -1,22 +0,0 @@
|
||||
==============================
|
||||
OpenStack Acceleration v1 APIs
|
||||
==============================
|
||||
|
||||
v1 APIs
|
||||
=======
|
||||
|
||||
This is a reference for the OpenStack Acceleration v1 API which is provided by
|
||||
the Cyborg project.
|
||||
|
||||
.. rest_expand_all::
|
||||
|
||||
.. include:: deployables.inc
|
||||
|
||||
Deprecated v1 APIs
|
||||
==================
|
||||
|
||||
This section contains references for v1 APIs which are deprecated and usually
|
||||
limited to some maximum microversion.
|
||||
|
||||
.. include:: accelerators.inc
|
||||
|
||||
118
api-ref/source/v2/device_profile.inc
Normal file
118
api-ref/source/v2/device_profile.inc
Normal file
@@ -0,0 +1,118 @@
|
||||
.. -*- rst -*-
|
||||
.. needs:body_verification
|
||||
|
||||
Device Profiles
|
||||
+++++++++++++++
|
||||
|
||||
Lists, creates, shows details for, updates and deletes device profiles.
|
||||
|
||||
A `device_profile
|
||||
<http://specs.openstack.org/openstack/cyborg-specs/specs/train/approved/device-profiles.html>`_
|
||||
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.
|
||||
|
||||
|
||||
List Device Profiles
|
||||
--------------------
|
||||
|
||||
.. rest_method:: GET /v2/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**
|
||||
|
||||
.. literalinclude:: ../../../doc/api_samples/device_profiles/device_profiles-list-resp.json
|
||||
:language: javascript
|
||||
|
||||
Get One Device Profile
|
||||
----------------------
|
||||
|
||||
.. rest_method:: GET /v2/device_profiles/{device_profile_uuid}
|
||||
|
||||
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
|
||||
=======
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- device_profile_uuid: device_profile_uuid
|
||||
|
||||
**Example response: get details of a specific device profile**
|
||||
|
||||
.. literalinclude:: ../../../doc/api_samples/device_profiles/device_profiles-getone-resp.json
|
||||
:language: javascript
|
||||
|
||||
Create Device Profile
|
||||
---------------------
|
||||
|
||||
.. rest_method:: POST /v2/device_profiles
|
||||
|
||||
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
|
||||
=======
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- name: device_prof_name_req
|
||||
- groups: device_prof_groups_req
|
||||
|
||||
**Example post curl with resource/trait**
|
||||
|
||||
.. literalinclude:: ../../../doc/api_samples/device_profiles/device_profiles-post-curl.json
|
||||
:language: javascript
|
||||
|
||||
**Example post curl with a cyborg property when bitstream is required**
|
||||
|
||||
.. literalinclude:: ../../../doc/api_samples/device_profiles/device_profiles-post-curl-with-bitstream.json
|
||||
:language: javascript
|
||||
|
||||
**Example response: create a device profile**
|
||||
|
||||
.. literalinclude:: ../../../doc/api_samples/device_profiles/device_profiles-create-resp.json
|
||||
:language: javascript
|
||||
|
||||
Delete One Device Profile by uuid
|
||||
---------------------------------
|
||||
|
||||
.. rest_method:: DELETE /v2/device_profiles/{device_profile_uuid}
|
||||
|
||||
Delete a device profile. No query parameters required.
|
||||
|
||||
Delete Multiple Device Profiles by names
|
||||
----------------------------------------
|
||||
|
||||
.. rest_method:: DELETE /v2/device_profiles?value={device_profile_name1},{device_profile_name2}
|
||||
|
||||
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
|
||||
12
api-ref/source/v2/index.rst
Normal file
12
api-ref/source/v2/index.rst
Normal file
@@ -0,0 +1,12 @@
|
||||
==============================
|
||||
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.
|
||||
|
||||
.. rest_expand_all::
|
||||
|
||||
.. include:: device_profile.inc
|
||||
26
api-ref/source/v2/parameters.yaml
Normal file
26
api-ref/source/v2/parameters.yaml
Normal file
@@ -0,0 +1,26 @@
|
||||
device_profile_uuid:
|
||||
description: |
|
||||
The UUID of the device_profile for your accelerator request.
|
||||
This must be a valid UUID otherwise API will return 400.
|
||||
in: path
|
||||
required: true
|
||||
type: string
|
||||
device_prof_groups_req:
|
||||
description: |
|
||||
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 <https://opendev.org/openstack/cyborg-specs/src/branch/master/specs/train/approved/device-profiles.rst#valid-accel-keys>`_.
|
||||
in: body
|
||||
required: true
|
||||
type: a list of dictionaries
|
||||
device_prof_name_req:
|
||||
description: |
|
||||
The display name of a device profile.
|
||||
in: body
|
||||
required: true
|
||||
type: string
|
||||
@@ -0,0 +1,17 @@
|
||||
{
|
||||
"links":[
|
||||
{
|
||||
"href":"http://192.168.23.76/accelerator/v2/device_profiles/1a939c88-0b01-408b-bab0-4c61d3a02d71",
|
||||
"rel":"self"
|
||||
}
|
||||
],
|
||||
"name":"afexample_3",
|
||||
"groups":[
|
||||
{
|
||||
"trait:CUSTOM_FUNCTION_ID_3AFB":"required",
|
||||
"resources:CUSTOM_ACCELERATOR_FPGA":"1",
|
||||
"trait:CUSTOM_FPGA_1":"required"
|
||||
}
|
||||
],
|
||||
"uuid":"1a939c88-0b01-408b-bab0-4c61d3a02d71"
|
||||
}
|
||||
@@ -0,0 +1,19 @@
|
||||
{
|
||||
"device_profile":{
|
||||
"links":[
|
||||
{
|
||||
"href":"http://192.168.32.217/accelerator/v2/device_profiles/5518a925-1c2c-49a2-a8bf-0927d9456f3e",
|
||||
"rel":"self"
|
||||
}
|
||||
],
|
||||
"name":"fpga-dp1",
|
||||
"groups":[
|
||||
{
|
||||
"trait:CUSTOM_CHENKE_TRAITS":"required",
|
||||
"resources:FPGA":"1",
|
||||
"accel:bitstream_id":"d5ca2f11-3108-4426-a11c-a959987565df"
|
||||
}
|
||||
],
|
||||
"uuid":"5518a925-1c2c-49a2-a8bf-0927d9456f3e"
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,37 @@
|
||||
{
|
||||
"device_profiles":[
|
||||
{
|
||||
"links":[
|
||||
{
|
||||
"href":"http://192.168.32.217/accelerator/v2/device_profiles/3d03fa5b-507c-4810-a344-759e9ef4337a",
|
||||
"rel":"self"
|
||||
}
|
||||
],
|
||||
"name":"bym-1",
|
||||
"groups":[
|
||||
{
|
||||
"resources:FPGA":"1",
|
||||
"trait:CUSTOM_FPGA_C260":"required"
|
||||
}
|
||||
],
|
||||
"uuid":"3d03fa5b-507c-4810-a344-759e9ef4337a"
|
||||
},
|
||||
{
|
||||
"links":[
|
||||
{
|
||||
"href":"http://192.168.32.217/accelerator/v2/device_profiles/5518a925-1c2c-49a2-a8bf-0927d9456f3e",
|
||||
"rel":"self"
|
||||
}
|
||||
],
|
||||
"name":"fpga-dp1",
|
||||
"groups":[
|
||||
{
|
||||
"trait:CUSTOM_CHENKE_TRAITS":"required",
|
||||
"resources:FPGA":"1",
|
||||
"accel:bitstream_id":"d5ca2f11-3108-4426-a11c-a959987565df"
|
||||
}
|
||||
],
|
||||
"uuid":"5518a925-1c2c-49a2-a8bf-0927d9456f3e"
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,10 @@
|
||||
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",
|
||||
"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"}]}]'
|
||||
@@ -0,0 +1,9 @@
|
||||
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",
|
||||
"groups": [{"resources:CUSTOM_ACCELERATOR_FPGA": "1",
|
||||
"trait:CUSTOM_FPGA_1": "required",
|
||||
"trait:CUSTOM_FUNCTION_ID_3AFB": "required"}]}]'
|
||||
Reference in New Issue
Block a user