openstack
/
ironic-inspector
Code Issues Proposed changes

Remove built-in API documentation in favour of API-REF 

A few items have been migrated from the former to the latter.

Change-Id: Icc4f00b872a2550ff886287d8f0844ee2593f296
This commit is contained in:
Dmitry Tantsur 2020-07-28 12:39:28 +02:00
parent cc7fcf4332
commit bd16d80005
8 changed files with 76 additions and 443 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
api-ref/source/index.rst
View File

@ -1,8 +1,11 @@
:tocdepth: 2 :tocdepth: 2
============================================ ============================
API of Hardware Introspection for Bare Metal Bare Metal Introspection API
============================================ ============================
By default **ironic-inspector** listens on ``0.0.0.0:5050``, port
can be changed in configuration. Protocol is JSON over HTTP.
.. rest_expand_all:: .. rest_expand_all::

4
api-ref/source/introspection-api-v1-continue.inc
View File

@ -39,11 +39,13 @@ List of mandatory hardware keys:
- inventory: inventory - inventory: inventory
- memory: memory - memory: memory
- cpu: cpu - cpu: cpu
- bmc_address: bmc_address
- interfaces: interfaces - interfaces: interfaces
- disks: disks - disks: disks
- root_disk: root_disk - root_disk: root_disk
- bmc_address: bmc_address
- boot_interface: boot_interface - boot_interface: boot_interface
- error: ramdisk_error
- logs: logs
**Example node introspection continue request:** **Example node introspection continue request:**

26
api-ref/source/introspection-api-versions.inc
View File

@ -79,3 +79,29 @@ Response Example
.. literalinclude:: samples/api-v1-root-response.json .. literalinclude:: samples/api-v1-root-response.json
:language: javascript :language: javascript
Version History
===============
* **1.0** version of API at the moment of introducing versioning.
* **1.1** adds endpoint to retrieve stored introspection data.
* **1.2** endpoints for manipulating introspection rules.
* **1.3** endpoint for canceling running introspection
* **1.4** endpoint for reapplying the introspection over stored data.
* **1.5** support for Ironic node names.
* **1.6** endpoint for rules creating returns 201 instead of 200 on success.
* **1.7** UUID, started_at, finished_at in the introspection status API.
* **1.8** support for listing all introspection statuses.
* **1.9** de-activate setting IPMI credentials, if IPMI credentials
are requested, API gets HTTP 400 response.
* **1.10** adds node state to the GET /v1/introspection/<Node ID> and
GET /v1/introspection API response data.
* **1.11** adds invert&multiple fields into rules response data
* **1.12** this version indicates that support for setting IPMI credentials
was completely removed from API (all versions).
* **1.13** adds ``manage_boot`` parameter for the introspection API.
* **1.14** allows formatting to be applied to strings nested in dicts and lists
in the actions of introspection rules.
* **1.15** allows reapply with provided introspection data from request.
* **1.16** adds ``scope`` field to introspection rule.
* **1.17** adds ``GET /v1/introspection/<node>/data/unprocessed``.

22
api-ref/source/parameters.yaml
View File

@ -156,7 +156,14 @@ id:
interfaces: interfaces:
description: | description: |
List of dictionaries with interfaces info, contains following keys: List of dictionaries with interfaces info, contains following keys:
``name``, ``ipv4_address``, ``mac_address``, ``client_id``.
* ``name`` interface name,
* ``ipv4_address`` IPv4 address of the interface,
* ``mac_address`` MAC (physical) address of the interface.
* ``client_id`` InfiniBand Client-ID, for Ethernet is None.
in: body in: body
required: true required: true
type: array type: array
@ -195,6 +202,13 @@ node_uuid:
in: body in: body
required: true required: true
type: string type: string
ramdisk_error:
description: |
An error that happened during ramdisk run, interpreted by the
``ramdisk_error`` processing hook.
in: body
required: false
type: string
rel: rel:
description: | description: |
The relationship between the version and the href. The relationship between the version and the href.
@ -211,6 +225,12 @@ root_disk:
description: | description: |
Default deployment root disk as calculated by the **ironic-python-agent** Default deployment root disk as calculated by the **ironic-python-agent**
algorithm. algorithm.
.. note::
The default processing hook ``root_disk_selection`` may change
``root_disk`` based on root device hints if node specify hints via
properties ``root_device`` key. See the `root device hints docs
<https://docs.openstack.org/ironic/latest/install/advanced.html#specifying-the-disk-for-deployment-root-device-hints>`_.
in: body in: body
required: true required: true
type: string type: string

430
doc/source/user/http-api.rst
View File

@ -1,432 +1,4 @@
HTTP API HTTP API
-------- --------
.. _http_api: See https://docs.openstack.org/api-ref/baremetal-introspection/
By default **ironic-inspector** listens on ``0.0.0.0:5050``, port
can be changed in configuration. Protocol is JSON over HTTP.
Start Introspection
~~~~~~~~~~~~~~~~~~~
``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.
Requires X-Auth-Token header with Keystone token for authentication.
Optional parameter:
* ``manage_boot`` boolean value, whether to manage boot (boot device, power
and firewall) for a node. Defaults to true.
Response:
* 202 - accepted introspection request
* 400 - bad request
* 401, 403 - missing or invalid authentication
* 404 - node cannot be found
Get Introspection Status
~~~~~~~~~~~~~~~~~~~~~~~~
``GET /v1/introspection/<Node ID>`` get hardware introspection status.
Requires X-Auth-Token header with Keystone token for authentication.
Response:
* 200 - OK
* 400 - bad request
* 401, 403 - missing or invalid authentication
* 404 - node cannot be found
Response body: JSON dictionary with keys:
* ``finished`` (boolean) whether introspection is finished
(``true`` on introspection completion or if it ends because of an error)
* ``state`` state of the introspection
* ``error`` error string or ``null``; ``Canceled by operator`` in
case introspection was aborted
* ``uuid`` node UUID
* ``started_at`` a UTC ISO8601 timestamp
* ``finished_at`` a UTC ISO8601 timestamp or ``null``
* ``links`` containing a self URL
Get All Introspection Statuses
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
``GET /v1/introspection`` get all hardware introspection statuses.
Requires X-Auth-Token header with Keystone token for authentication.
Returned status list is sorted by the ``started_at, uuid`` attribute pair,
newer items first, and is paginated with these query string fields:
* ``marker`` the UUID of the last node returned previously
* ``limit`` default, max: ``CONF.api_max_limit``
Response:
* 200 - OK
* 400 - bad request
* 401, 403 - missing or invalid authentication
Response body: a JSON object containing a list of status objects::
{
'introspection': [
{
'finished': false,
'state': 'waiting',
'error': null,
...
},
...
]
}
Each status object contains these keys:
* ``finished`` (boolean) whether introspection is finished
(``true`` on introspection completion or if it ends because of an error)
* ``state`` state of the introspection
* ``error`` error string or ``null``; ``Canceled by operator`` in
case introspection was aborted
* ``uuid`` node UUID
* ``started_at`` an UTC ISO8601 timestamp
* ``finished_at`` an UTC ISO8601 timestamp or ``null``
Abort Running Introspection
~~~~~~~~~~~~~~~~~~~~~~~~~~~
``POST /v1/introspection/<Node ID>/abort`` abort running introspection.
Requires X-Auth-Token header with Keystone token for authentication.
Response:
* 202 - accepted
* 400 - bad request
* 401, 403 - missing or invalid authentication
* 404 - node cannot be found
* 409 - inspector has locked this node for processing
Get Introspection Data
~~~~~~~~~~~~~~~~~~~~~~
``GET /v1/introspection/<Node ID>/data`` get stored data from successful
introspection.
Requires X-Auth-Token header with Keystone token for authentication.
Response:
* 200 - OK
* 400 - bad request
* 401, 403 - missing or invalid authentication
* 404 - data cannot be found or data storage not configured
Response body: JSON dictionary with introspection data. For more
details about the inventory key, refer to the
:ironic-python-agent-doc:`ironic-python-agent documentation
<admin/how_it_works.html#inspection-data>`.
.. note::
We do not provide any backward compatibility guarantees regarding the
format and contents of the stored data, other than the ``inventory``.
Notably, it depends on the ramdisk
used and plugins enabled both in the ramdisk and in inspector itself.
Get Unprocessed Introspection Data
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
``GET /v1/introspection/<Node ID>/data/unprocessed`` get raw (unprocessed) data
from introspection.
Requires X-Auth-Token header with Keystone token for authentication.
Response:
* 200 - OK
* 400 - bad request
* 401, 403 - missing or invalid authentication
* 404 - data cannot be found or data storage not configured
Response body: JSON dictionary with introspection data. For more
details about the inventory key, refer to the
:ironic-python-agent-doc:`ironic-python-agent documentation
<admin/how_it_works.html#inspection-data>`.
.. note::
We do not provide any backward compatibility guarantees regarding the
format and contents of the stored data, other than the ``inventory``.
Notably, it depends on the ramdisk
used and plugins enabled both in the ramdisk and in inspector itself.
Reapply introspection on stored data
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
``POST /v1/introspection/<Node ID>/data/unprocessed`` to trigger
introspection on stored unprocessed data. No data is allowed to be
sent along with the request.
Requires X-Auth-Token header with Keystone token for authentication.
Requires enabling Swift store in processing section of the
configuration file.
Response:
* 202 - accepted
* 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
Introspection Rules
~~~~~~~~~~~~~~~~~~~
See :ref:`rules <introspection_rules>` for details.
All these API endpoints require X-Auth-Token header with Keystone token for
authentication.
* ``POST /v1/rules`` create a new introspection rule.
Request body: JSON dictionary with keys:
* ``conditions`` rule conditions, see :ref:`rules <introspection_rules>`
* ``actions`` rule actions, see :ref:`rules <introspection_rules>`
* ``description`` (optional) human-readable description
* ``uuid`` (optional) rule UUID, autogenerated if missing
Response
* 200 - OK for API version < 1.6
* 201 - OK for API version 1.6 and higher
* 400 - bad request
Response body: JSON dictionary with introspection rule representation (the
same as above with UUID filled in).
* ``GET /v1/rules`` list all introspection rules.
Response
* 200 - OK
Response body: JSON dictionary with key ``rules`` - list of short rule
representations. Short rule representation is a JSON dictionary with keys:
* ``uuid`` rule UUID
* ``description`` human-readable description
* ``links`` list of HTTP links, use one with ``rel=self`` to get the full
rule details
* ``DELETE /v1/rules`` delete all introspection rules.
Response
* 204 - OK
* ``GET /v1/rules/<UUID>`` get one introspection rule by its ``<UUID>``.
Response
* 200 - OK
* 404 - not found
Response body: JSON dictionary with introspection rule representation
(see ``POST /v1/rules`` above).
* ``DELETE /v1/rules/<UUID>`` delete one introspection rule by its ``<UUID>``.
Response
* 204 - OK
* 404 - not found
Ramdisk Callback
~~~~~~~~~~~~~~~~
.. _ramdisk_callback:
``POST /v1/continue`` internal endpoint for the ramdisk to post back
discovered data. Should not be used for anything other than implementing
the ramdisk. Request body: JSON dictionary with at least these keys:
* ``inventory`` full
:ironic-python-agent-doc:`hardware inventory
<admin/how_it_works.html#hardware-inventory>`
from the ironic-python-agent with at least the following keys:
* ``memory`` memory information containing at least key ``physical_mb`` -
physical memory size as reported by dmidecode,
* ``cpu`` CPU information containing at least keys ``count`` (CPU count) and
``architecture`` (CPU architecture, e.g. ``x86_64``),
* ``bmc_address`` IP address of the node's BMC,
* ``interfaces`` list of dictionaries with the following keys:
* ``name`` interface name,
* ``ipv4_address`` IPv4 address of the interface,
* ``mac_address`` MAC (physical) address of the interface.
* ``client_id`` InfiniBand Client-ID, for Ethernet is None.
* ``disks`` list of disk block devices containing at least ``name`` and
``size`` (in bytes) keys. In case ``disks`` are not provided
**ironic-inspector** assumes that this is a disk-less node.
* ``root_disk`` default deployment root disk as calculated by the
ironic-python-agent algorithm.
.. note::
**ironic-inspector** default plugin ``root_disk_selection`` may change
``root_disk`` based on root device hints if node specify hints via
properties ``root_device`` key. See
:ironic-doc:`Specifying the disk for deployment root device hints <install/advanced.html#specifying-the-disk-for-deployment-root-device-hints>`
for more details.
* ``boot_interface`` MAC address of the NIC that the machine PXE booted from
either in standard format ``11:22:33:44:55:66`` or in *PXELinux* ``BOOTIF``
format ``01-11-22-33-44-55-66``. Strictly speaking, this key is optional,
but some features will now work as expected, if it is not provided.
Optionally the following keys might be provided:
* ``error`` error happened during ramdisk run, interpreted by
``ramdisk_error`` plugin.
* ``logs`` base64-encoded logs from the ramdisk.
.. note::
This list highly depends on enabled plugins, provided above are
expected keys for the default set of plugins. See
:ref:`plugins <introspection_plugins>` for details.
.. note::
This endpoint is not expected to be versioned, though versioning will work
on it.
Response:
* 200 - OK
* 400 - bad request
* 403 - node is not on introspection
* 404 - node cannot be found or multiple nodes found
Response body: JSON dictionary with ``uuid`` key.
Error Response
~~~~~~~~~~~~~~
If an error happens during request processing, **Ironic Inspector** returns
a response with an appropriate HTTP code set, e.g. 400 for bad request or
404 when something was not found (usually node in cache or node in ironic).
The following JSON body is returned::
{
"error": {
"message": "Full error message"
}
}
This body may be extended in the future to include details that are more error
specific.
API Versioning
~~~~~~~~~~~~~~
The API supports optional API versioning. You can query for minimum and
maximum API version supported by the server. You can also declare required API
version in your requests, so that the server rejects request of unsupported
version.
.. note::
Versioning was introduced in **Ironic Inspector 2.1.0**.
All versions must be supplied as string in form of ``X.Y``, where ``X`` is a
major version and is always ``1`` for now, ``Y`` is a minor version.
* If ``X-OpenStack-Ironic-Inspector-API-Version`` header is sent with request,
the server will check if it supports this version. HTTP error 406 will be
returned for unsupported API version.
* All HTTP responses contain
``X-OpenStack-Ironic-Inspector-API-Minimum-Version`` and
``X-OpenStack-Ironic-Inspector-API-Maximum-Version`` headers with minimum
and maximum API versions supported by the server.
.. note::
Maximum is server API version used by default.
API Discovery
~~~~~~~~~~~~~
The API supports API discovery. You can query different parts of the API to
discover what other endpoints are available.
* ``GET /`` List API Versions
Response:
* 200 - OK
Response body: JSON dictionary containing a list of ``versions``, each
version contains:
* ``status`` Either CURRENT or SUPPORTED
* ``id`` The version identifier
* ``links`` A list of links to this version endpoint containing:
* ``href`` The URL
* ``rel`` The relationship between the version and the href
* ``GET /v1`` List API v1 resources
Response:
* 200 - OK
Response body: JSON dictionary containing a list of ``resources``, each
resource contains:
* ``name`` The name of this resources
* ``links`` A list of link to this resource containing:
* ``href`` The URL
* ``rel`` The relationship between the resource and the href
Version History
^^^^^^^^^^^^^^^
* **1.0** version of API at the moment of introducing versioning.
* **1.1** adds endpoint to retrieve stored introspection data.
* **1.2** endpoints for manipulating introspection rules.
* **1.3** endpoint for canceling running introspection
* **1.4** endpoint for reapplying the introspection over stored data.
* **1.5** support for Ironic node names.
* **1.6** endpoint for rules creating returns 201 instead of 200 on success.
* **1.7** UUID, started_at, finished_at in the introspection status API.
* **1.8** support for listing all introspection statuses.
* **1.9** de-activate setting IPMI credentials, if IPMI credentials
are requested, API gets HTTP 400 response.
* **1.10** adds node state to the GET /v1/introspection/<Node ID> and
GET /v1/introspection API response data.
* **1.11** adds invert&multiple fields into rules response data
* **1.12** this version indicates that support for setting IPMI credentials
was completely removed from API (all versions).
* **1.13** adds ``manage_boot`` parameter for the introspection API.
* **1.14** allows formatting to be applied to strings nested in dicts and lists
in the actions of introspection rules.
* **1.15** allows reapply with provided introspection data from request.
* **1.16** adds ``scope`` field to introspection rule.
* **1.17** adds ``GET /v1/introspection/<node>/data/unprocessed``.

12
doc/source/user/index.rst
View File

@ -20,10 +20,8 @@ How to use Ironic Inspector
HTTP API Reference HTTP API Reference
------------------ ------------------
.. toctree:: * `Bare Metal Introspection API Reference
:maxdepth: 2 <https://docs.openstack.org/api-ref/baremetal-introspection/>`_.
http-api
Troubleshooting Troubleshooting
--------------- ---------------
@ -32,3 +30,9 @@ Troubleshooting
:maxdepth: 2 :maxdepth: 2
troubleshooting troubleshooting
.. toctree::
:hidden:
http-api

12
doc/source/user/usage.rst
View File

@ -3,10 +3,12 @@ Usage
.. _usage_guide: .. _usage_guide:
Refer to :ref:`api <http_api>` for information on the HTTP API. Refer to the `API reference`_ for information on the HTTP API.
Refer to the :python-ironic-inspector-client-doc:`client documentation <>` Refer to the :python-ironic-inspector-client-doc:`client documentation <>`
for information on how to use CLI and Python library. for information on how to use CLI and Python library.
.. _API reference: https://docs.openstack.org/api-ref/baremetal-introspection/
Using from Ironic API Using from Ironic API
~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~
@ -57,7 +59,7 @@ Please refer to the command below to import introspection rule::
openstack baremetal introspection rule import <json file> openstack baremetal introspection rule import <json file>
Available conditions and actions are defined by plugins, and can be extended, Available conditions and actions are defined by plugins, and can be extended,
see :ref:`contributing_link` for details. See :ref:`api <http_api>` for see :ref:`contributing_link` for details. See the `API reference`_ for
specific calls to define introspection rules. specific calls to define introspection rules.
Conditions Conditions
@ -212,7 +214,7 @@ needed:
``ramdisk_error`` ``ramdisk_error``
reports error, if ``error`` field is set by the ramdisk, also optionally reports error, if ``error`` field is set by the ramdisk, also optionally
stores logs from ``logs`` field, see :ref:`api <http_api>` for details. stores logs from ``logs`` field, see the `API reference`_ for details.
``capabilities`` ``capabilities``
detect node capabilities: CPU, boot mode, etc. See `Capabilities detect node capabilities: CPU, boot mode, etc. See `Capabilities
Detection`_ for more details. Detection`_ for more details.
@ -287,7 +289,9 @@ arbitrary fields to set on discovery, for example:
The ``enroll`` hook will also set the ``ipmi_address`` property on the new The ``enroll`` hook will also set the ``ipmi_address`` property on the new
node, if its available in the introspection data we received, node, if its available in the introspection data we received,
see :ref:`ramdisk_callback <ramdisk_callback>`. see `ramdisk callback`_.
.. _ramdisk callback: https://docs.openstack.org/api-ref/baremetal-introspection/?expanded=ramdisk-callback-detail#ramdisk-callback
Once the ``enroll`` hook is finished, **ironic-inspector** will process the Once the ``enroll`` hook is finished, **ironic-inspector** will process the
introspection data in the same way it would for an identified node. It runs introspection data in the same way it would for an identified node. It runs

4
doc/source/user/workflow.rst
View File

@ -60,7 +60,7 @@ Usual hardware introspection flow is as follows:
the ``keep_ports`` option should be also set to ``all``. This will ensure the ``keep_ports`` option should be also set to ``all``. This will ensure
no manually added ports will be deleted. no manually added ports will be deleted.
* Separate API (see :ref:`usage <usage_guide>` and :ref:`api <http_api>`) can * Separate API (see :ref:`usage <usage_guide>` and `API reference`_) can
be used to query introspection results for a given node. be used to query introspection results for a given node.
* Nodes are put in the correct state for deploying as described in * Nodes are put in the correct state for deploying as described in
@ -69,6 +69,8 @@ Usual hardware introspection flow is as follows:
Starting DHCP server and configuring PXE boot environment is not part of this Starting DHCP server and configuring PXE boot environment is not part of this
package and should be done separately. package and should be done separately.
.. _API reference: https://docs.openstack.org/api-ref/baremetal-introspection/
State machine diagram State machine diagram
--------------------- ---------------------