Revise api-ref docs

Follow up to https://review.openstack.org/#/c/495752

Addressed some comments from rloo, as well as some other issues.

Change-Id: I3cdcac63b43c6b51f913d230153c1f8650426478
This commit is contained in:
Kaifeng Wang 2018-10-26 15:21:53 +08:00
parent bce5b3ec35
commit 6c4e6760c4
5 changed files with 31 additions and 33 deletions

View File

@ -1,8 +1,8 @@
:tocdepth: 2
=========================================
Hardware Introspection for Bare Metal API
=========================================
============================================
API of Hardware Introspection for Bare Metal
============================================
.. rest_expand_all::

View File

@ -5,14 +5,13 @@ Process introspection data
==========================
After the ramdisk collects the required information from the bare metal
node, it should post it back to Inspector via ``POST /v1/continue`` method.
node, it should post it back to Inspector via ``POST /v1/continue`` API.
.. warning::
Operators are reminded not to expose the Ironic Inspector API to
unsecured networks. Below method is available to *unauthenticated*
clients because **ironic-python-agent** ramdisk does not have access to
keystone credentials.
unsecured and untrusted networks. API below is available to
*unauthenticated* clients because **ironic-python-agent** ramdisk
does not have access to keystone credentials.
Ramdisk Callback
@ -20,8 +19,8 @@ Ramdisk Callback
.. rest_method:: POST /v1/continue
It is internal method for the ramdisk to post back all discovered data.
This should not be used for anything other than the ramdisk.
It is the API for the ramdisk to post back all discovered data.
This should not be used for clients other than the ramdisk.
Full list of hardware inventory keys may be found in **ironic-python-agent**
documentation: `hardware inventory <https://docs.openstack.org/ironic-python-agent/latest/admin/how_it_works.html#hardware-inventory>`_.
@ -45,7 +44,6 @@ List of mandatory hardware keys:
- disks: disks
- root_disk: root_disk
- boot_interface: boot_interface
- logs: logs
**Example node introspection continue request:**

View File

@ -4,9 +4,10 @@
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, abort introspection, get introspection status, and 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
===================
@ -16,8 +17,9 @@ Start Introspection
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.
In the case of missing or invalid authentication, the response code will be
401 and 403 respectively.
If Inspector doesn't find node {node_id}, it will return 404.
Normal response codes: 202
@ -64,7 +66,7 @@ Response
--------
The response will contain the complete introspection info, like
create, finish time, introspection state, errors if any.
start, finish time, introspection state, errors if any.
.. rest_parameters:: parameters.yaml
@ -197,13 +199,12 @@ Reapply Introspection on stored data
.. rest_method:: POST /v1/introspection/{node_id}/data/unprocessed
This method riggers introspection on stored unprocessed data.
This method triggers 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.
Requires enabling introspection storage backend via ``[processing]store_data``.
Normal response codes: 202

View File

@ -84,17 +84,6 @@ Response
:language: javascript
Delete Introspection Rules
==========================
.. rest_method:: DELETE /v1/rules
Delete all introspection rules
Normal response codes: 204
Get Introspection Rule
======================
@ -102,7 +91,7 @@ Get Introspection Rule
Get one introspection rule by its ``uuid``
Normal response codes: 202
Normal response codes: 200
Error codes:
@ -134,6 +123,16 @@ The response will contain full rule object:
:language: javascript
Delete Introspection Rules
==========================
.. rest_method:: DELETE /v1/rules
Delete all introspection rules
Normal response codes: 204
Delete Introspection Rule
=========================

View File

@ -191,7 +191,7 @@ name:
required: true
type: string
node_uuid:
description: Ironic node uui
description: Ironic node UUID.
in: body
required: true
type: string