05a86b3d57
Add initial API reference, which covers all inspector endpoits. The conf.py and the tox environment are stolen from ironic. Co-Authored-By: Kaifeng Wang <kaifeng.w@gmail.com> Change-Id: I5009e8708dcad8ab25380f7bf574125d6e758ef5
227 lines
4.6 KiB
ReStructuredText
227 lines
4.6 KiB
ReStructuredText
.. -*- rst -*-
|
|
|
|
==================
|
|
Node Introspection
|
|
==================
|
|
|
|
Start, abort introspection, get introspection status, get introspection data
|
|
are done through the ``/v1/introspection`` resource. There are also several
|
|
sub-resources, which allow further actions to be performed on introspection.
|
|
|
|
Start Introspection
|
|
===================
|
|
|
|
.. rest_method:: POST /v1/introspection/{node_id}
|
|
|
|
Initiate hardware introspection for node {node_id} . All power management
|
|
configuration for this node needs to be done prior to calling the endpoint.
|
|
|
|
In case missing or invalid authentication response code will be 401 and 403.
|
|
If Inspector don't find node {node_id}, it will return 404.
|
|
|
|
Normal response codes: 202
|
|
|
|
Error codes: 400, 401, 403, 404
|
|
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- node_id: node_id
|
|
- manage_boot: manage_boot
|
|
|
|
|
|
Response
|
|
--------
|
|
|
|
The response will be empty body.
|
|
|
|
Get Introspection status
|
|
========================
|
|
|
|
.. rest_method:: GET /v1/introspection/{node_id}
|
|
|
|
Get node introspection status.
|
|
|
|
In case missing or invalid authentication response code will be 401 and 403.
|
|
If Inspector don't find node {node_id}, it will return 404.
|
|
|
|
Normal response codes: 200
|
|
|
|
Error codes: 400, 401, 403, 404
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- node_id: node_id
|
|
|
|
|
|
Response
|
|
--------
|
|
|
|
The response will contain the complete introspection info, like
|
|
create, finish time, introspection state, errors if any.
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- error: error
|
|
- finished: finished
|
|
- finished_at: finished_at
|
|
- links: links
|
|
- started_at: started_at
|
|
- state: state
|
|
- uuid: node_id
|
|
|
|
**Example JSON representation of an introspection:**
|
|
|
|
.. literalinclude:: samples/api-v1-get-introspection-response.json
|
|
:language: javascript
|
|
|
|
|
|
List All Introspection statuses
|
|
===============================
|
|
|
|
.. rest_method:: GET /v1/introspection/
|
|
|
|
Returned status list is sorted by the ``started_at, uuid`` attribute pair,
|
|
newer items first.
|
|
|
|
In case missing or invalid authentication response code will be 401 and 403.
|
|
|
|
Normal response codes: 200
|
|
|
|
Error codes: 400, 401, 403
|
|
|
|
Request
|
|
-------
|
|
|
|
Status list may be paginated with these query string fields:
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- marker: marker
|
|
- limit: limit
|
|
|
|
|
|
Response
|
|
--------
|
|
|
|
The response will contain a list of status objects:
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- error: error
|
|
- finished: finished
|
|
- finished_at: finished_at
|
|
- links: links
|
|
- started_at: started_at
|
|
- state: state
|
|
- uuid: node_id
|
|
|
|
|
|
**Example JSON representation of an introspection:**
|
|
|
|
.. literalinclude:: samples/api-v1-get-introspections-response.json
|
|
:language: javascript
|
|
|
|
|
|
Abort Introspection
|
|
===================
|
|
|
|
.. rest_method:: POST /v1/introspection/{node_id}/abort
|
|
|
|
Abort running introspection.
|
|
|
|
Normal response codes: 202
|
|
|
|
Error codes:
|
|
|
|
* 400 - bad request
|
|
* 401, 403 - missing or invalid authentication
|
|
* 404 - node cannot be found
|
|
* 409 - inspector has locked this node for processing
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- node_id: node_id
|
|
|
|
|
|
Get Introspection data
|
|
======================
|
|
|
|
.. rest_method:: GET /v1/introspection/{node_id}/data
|
|
|
|
Return stored data from successful introspection.
|
|
|
|
.. note::
|
|
We do not provide any backward compatibility guarantees regarding the
|
|
format and contents of the stored data. Notably, it depends on the ramdisk
|
|
used and plugins enabled both in the ramdisk and in inspector itself.
|
|
|
|
Normal response codes: 200
|
|
|
|
Error codes:
|
|
|
|
* 400 - bad request
|
|
* 401, 403 - missing or invalid authentication
|
|
* 404 - data cannot be found or data storage not configured
|
|
|
|
Request
|
|
-------
|
|
|
|
Status list may be paginated with these query string fields:
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- node_id: node_id
|
|
- limit: limit
|
|
|
|
|
|
Response
|
|
--------
|
|
|
|
The response will contain introspection data in the form of json string.
|
|
|
|
**Example JSON representation of an introspection data:**
|
|
|
|
.. literalinclude:: samples/api-v1-data-introspection-response.json
|
|
:language: javascript
|
|
|
|
|
|
Reapply Introspection on stored data
|
|
====================================
|
|
|
|
.. rest_method:: POST /v1/introspection/{node_id}/data/unprocessed
|
|
|
|
This method riggers introspection on stored unprocessed data.
|
|
No data is allowed to be sent along with the request.
|
|
|
|
.. note::
|
|
|
|
Requires enabling Swift store in processing section of the
|
|
configuration file.
|
|
|
|
Normal response codes: 202
|
|
|
|
Error codes:
|
|
|
|
* 400 - bad request or store not configured
|
|
* 401, 403 - missing or invalid authentication
|
|
* 404 - node not found for Node ID
|
|
* 409 - inspector locked node for processing
|
|
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- node_id: node_id
|