Follow up to api-ref revision

Addressing commments from https://review.openstack.org/#/c/613515

Contents about introspection sub resouces are moved to a new file.

Change-Id: Icd3efb902e6f836dad653011a96edc84a3feea7c
This commit is contained in:
Kaifeng Wang 2019-03-14 15:24:19 +08:00
parent 0d5bc4b99d
commit 688c6ebd15
4 changed files with 132 additions and 127 deletions

View File

@ -8,5 +8,6 @@ API of Hardware Introspection for Bare Metal
.. include:: introspection-api-versions.inc .. include:: introspection-api-versions.inc
.. include:: introspection-api-v1-introspection.inc .. include:: introspection-api-v1-introspection.inc
.. include:: introspection-api-v1-introspection-management.inc
.. include:: introspection-api-v1-continue.inc .. include:: introspection-api-v1-continue.inc
.. include:: introspection-api-v1-rules.inc .. include:: introspection-api-v1-rules.inc

View File

@ -0,0 +1,100 @@
.. -*- rst -*-
========================================
Introspection Management (introspection)
========================================
Abort introspection, get introspection data and reapply introspection can be
done through introspection sub-resources.
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
-------
.. rest_parameters:: parameters.yaml
- node_id: node_id
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 triggers introspection on stored unprocessed data.
No data is allowed to be sent along with the request.
.. note::
Requires enabling introspection storage backend via ``[processing]store_data``.
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

View File

@ -1,13 +1,12 @@
.. -*- rst -*- .. -*- rst -*-
================== ==================================
Node Introspection Node Introspection (introspection)
================== ==================================
Start, abort introspection, get introspection status, and get introspection Start introspection, get introspection status are done through the
data are done through the ``/v1/introspection`` resource. There are also ``/v1/introspection`` resource. There are also several sub-resources, which
several sub-resources, which allow further actions to be performed on allow further actions to be performed on introspection.
introspection.
Start Introspection Start Introspection
=================== ===================
@ -35,55 +34,6 @@ Request
- manage_boot: manage_boot - 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
start, 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 List All Introspection statuses
=============================== ===============================
@ -131,49 +81,19 @@ The response will contain a list of status objects:
:language: javascript :language: javascript
Abort Introspection Show Introspection status
=================== =========================
.. rest_method:: POST /v1/introspection/{node_id}/abort .. rest_method:: GET /v1/introspection/{node_id}
Abort running introspection. Show node introspection status.
Normal response codes: 202 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.
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 Normal response codes: 200
Error codes: Error codes: 400, 401, 403, 404
* 400 - bad request
* 401, 403 - missing or invalid authentication
* 404 - data cannot be found or data storage not configured
Request Request
------- -------
@ -186,39 +106,22 @@ Request
Response Response
-------- --------
The response will contain introspection data in the form of json string. The response will contain the complete introspection info, like
start, finish time, introspection state, errors if any.
**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 triggers introspection on stored unprocessed data.
No data is allowed to be sent along with the request.
.. note::
Requires enabling introspection storage backend via ``[processing]store_data``.
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 .. rest_parameters:: parameters.yaml
- node_id: node_id - 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

View File

@ -5,7 +5,8 @@ Introspection Rules
=================== ===================
Simple JSON-based DSL to define rules, which run during introspection. Simple JSON-based DSL to define rules, which run during introspection.
See `<https://docs.openstack.org/ironic-inspector/latest/user/usage.html#introspection-rules>`_
for more information on rules.
Create Introspection Rule Create Introspection Rule
========================= =========================