Numerous improvements in the documentation
* Flatten the directory structure (we don't have that many doc files) * Dropped HTTP-API from the root so that we don't maintain 2 copies * Fixed links all over the place * Leave one copy of README text in the root and include it in docs * Update 'tox -epep8' to also check docs Change-Id: Ic14cb73668544be27c6b96b384f93b239e49acfd
This commit is contained in:
parent
ef8fc580f2
commit
99732e5297
103
README.rst
103
README.rst
@ -7,10 +7,6 @@ properties discovery is a process of getting hardware parameters required for
|
|||||||
scheduling from a bare metal node, given it's power management credentials
|
scheduling from a bare metal node, given it's power management credentials
|
||||||
(e.g. IPMI address, user name and password).
|
(e.g. IPMI address, user name and password).
|
||||||
|
|
||||||
A special ramdisk is required to collect the information on a
|
|
||||||
node. The default one can be built using diskimage-builder_ and
|
|
||||||
`ironic-discoverd-ramdisk element`_ (see Configuration_ below).
|
|
||||||
|
|
||||||
* Free software: Apache license
|
* Free software: Apache license
|
||||||
* Source: http://git.openstack.org/cgit/openstack/ironic-inspector
|
* Source: http://git.openstack.org/cgit/openstack/ironic-inspector
|
||||||
* Bugs: http://bugs.launchpad.net/ironic-inspector
|
* Bugs: http://bugs.launchpad.net/ironic-inspector
|
||||||
@ -19,106 +15,11 @@ node. The default one can be built using diskimage-builder_ and
|
|||||||
* Python client library and CLI tool: `python-ironic-inspector-client
|
* Python client library and CLI tool: `python-ironic-inspector-client
|
||||||
<https://pypi.python.org/pypi/python-ironic-inspector-client>`_.
|
<https://pypi.python.org/pypi/python-ironic-inspector-client>`_.
|
||||||
|
|
||||||
Refer to CONTRIBUTING.rst_ for instructions on how to contribute.
|
|
||||||
|
|
||||||
.. _Ironic: https://wiki.openstack.org/wiki/Ironic
|
.. _Ironic: https://wiki.openstack.org/wiki/Ironic
|
||||||
.. _PyPI: https://pypi.python.org/pypi/ironic-inspector
|
|
||||||
.. _CONTRIBUTING.rst: https://github.com/openstack/ironic-inspector/blob/master/CONTRIBUTING.rst
|
|
||||||
.. _diskimage-builder: https://github.com/openstack/diskimage-builder
|
|
||||||
.. _ironic-discoverd-ramdisk element: https://github.com/openstack/diskimage-builder/tree/master/elements/ironic-discoverd-ramdisk
|
|
||||||
.. _Configuration: https://github.com/openstack/ironic-inspector/blob/master/doc/source/install-guide.rst
|
|
||||||
|
|
||||||
.. note::
|
.. note::
|
||||||
**ironic-inspector** was called *ironic-discoverd* before version 2.0.0.
|
**ironic-inspector** was called *ironic-discoverd* before version 2.0.0.
|
||||||
|
|
||||||
Version Support Matrix
|
For information on any current or prior version, see `the release notes`_.
|
||||||
----------------------
|
|
||||||
|
|
||||||
**ironic-inspector** currently requires bare metal API version ``1.6`` to be
|
|
||||||
provided by Ironic. This version is available starting with Ironic Kilo
|
|
||||||
release.
|
|
||||||
|
|
||||||
Here is a mapping between Ironic versions and supported **ironic-inspector**
|
|
||||||
versions. The Standalone column shows which **ironic-inspector** versions can
|
|
||||||
be used in standalone mode with each Ironic version. The Inspection Interface
|
|
||||||
column shows which **ironic-inspector** versions can be used with the Ironic
|
|
||||||
inspection interface in each version of Ironic.
|
|
||||||
|
|
||||||
+--------------+-------------------------------+
|
|
||||||
|Ironic Version| Inspector (Discoverd) Version |
|
|
||||||
| +----------+--------------------+
|
|
||||||
| |Standalone|Inspection Interface|
|
|
||||||
+==============+==========+====================+
|
|
||||||
|Juno |1.0 |N/A |
|
|
||||||
+--------------+----------+--------------------+
|
|
||||||
|Kilo |1.0 - 2.2 |1.0 - 1.1 |
|
|
||||||
+--------------+----------+--------------------+
|
|
||||||
|Liberty |1.1 - 2.X |2.0 - 2.X |
|
|
||||||
+--------------+----------+--------------------+
|
|
||||||
|
|
||||||
.. note::
|
|
||||||
``2.X`` means we don't have specific plans on deprecating support for this
|
|
||||||
Ironic version. This does not imply that we'll support it forever though.
|
|
||||||
|
|
||||||
Workflow
|
|
||||||
--------
|
|
||||||
|
|
||||||
Usual hardware introspection flow is as follows:
|
|
||||||
|
|
||||||
* Operator enrolls nodes into Ironic_ e.g. via ironic CLI command.
|
|
||||||
Power management credentials should be provided to Ironic at this step.
|
|
||||||
|
|
||||||
* Nodes are put in the correct state for introspection as described in
|
|
||||||
:ref:`node_states`.
|
|
||||||
|
|
||||||
* Operator sends nodes on introspection using **ironic-inspector** API or CLI
|
|
||||||
(see Usage_).
|
|
||||||
|
|
||||||
* On receiving node UUID **ironic-inspector**:
|
|
||||||
|
|
||||||
* validates node power credentials, current power and provisioning states,
|
|
||||||
* allows firewall access to PXE boot service for the nodes,
|
|
||||||
* issues reboot command for the nodes, so that they boot the ramdisk.
|
|
||||||
|
|
||||||
* The ramdisk collects the required information and posts it back to
|
|
||||||
**ironic-inspector**.
|
|
||||||
|
|
||||||
* On receiving data from the ramdisk, **ironic-inspector**:
|
|
||||||
|
|
||||||
* validates received data,
|
|
||||||
* finds the node in Ironic database using it's BMC address (MAC address in
|
|
||||||
case of SSH driver),
|
|
||||||
* fills missing node properties with received data and creates missing ports.
|
|
||||||
|
|
||||||
.. note::
|
|
||||||
**ironic-inspector** is responsible to create Ironic ports for some or all
|
|
||||||
NIC's found on the node. **ironic-inspector** is also capable of
|
|
||||||
deleting ports that should not be present. There are two important
|
|
||||||
configuration options that affect this behavior: ``add_ports`` and
|
|
||||||
``keep_ports`` (please refer to ``example.conf`` for detailed explanation).
|
|
||||||
|
|
||||||
Default values as of **ironic-inspector** 1.1.0 are ``add_ports=pxe``,
|
|
||||||
``keep_ports=all``, which means that only one port will be added, which is
|
|
||||||
associated with NIC the ramdisk PXE booted from. No ports will be deleted.
|
|
||||||
This setting ensures that deploying on introspected nodes will succeed
|
|
||||||
despite `Ironic bug 1405131
|
|
||||||
<https://bugs.launchpad.net/ironic/+bug/1405131>`_.
|
|
||||||
|
|
||||||
Ironic inspection feature by default requires different settings:
|
|
||||||
``add_ports=all``, ``keep_ports=present``, which means that ports will be
|
|
||||||
created for all detected NIC's, and all other ports will be deleted.
|
|
||||||
Refer to the `Ironic inspection documentation`_ for details.
|
|
||||||
|
|
||||||
* Separate API (see Usage_) can be used to query introspection results
|
|
||||||
for a given node.
|
|
||||||
|
|
||||||
* Nodes are put in the correct state for deploying as described in
|
|
||||||
:ref:`node_states`.
|
|
||||||
|
|
||||||
Starting DHCP server and configuring PXE boot environment is not part of this
|
|
||||||
package and should be done separately.
|
|
||||||
|
|
||||||
.. _instack-undercloud: https://www.rdoproject.org/Deploying_an_RDO_Undercloud_with_Instack
|
|
||||||
.. _Ironic inspection documentation: http://docs.openstack.org/developer/ironic/deploy/install-guide.html#hardware-inspection
|
|
||||||
.. _Usage: https://github.com/openstack/ironic-inspector/blob/master/doc/source/usage.rst
|
|
||||||
|
|
||||||
|
.. _the release notes: http://docs.openstack.org/releasenotes/ironic-inspector/
|
||||||
|
@ -1,274 +0,0 @@
|
|||||||
HTTP API
|
|
||||||
--------
|
|
||||||
|
|
||||||
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/<UUID>`` initiate hardware introspection for node
|
|
||||||
``<UUID>``. All power management configuration for this node needs to be done
|
|
||||||
prior to calling the endpoint (except when `Setting IPMI Credentials`_).
|
|
||||||
|
|
||||||
Requires X-Auth-Token header with Keystone token for authentication.
|
|
||||||
|
|
||||||
Optional parameters:
|
|
||||||
|
|
||||||
* ``new_ipmi_password`` if set, **ironic-inspector** will try to set IPMI
|
|
||||||
password on the machine to this value. Power credentials validation will be
|
|
||||||
skipped and manual power on will be required. See `Setting IPMI
|
|
||||||
credentials`_ for details.
|
|
||||||
|
|
||||||
* ``new_ipmi_username`` provides new IPMI user name in addition to password
|
|
||||||
set by ``new_ipmi_password``. Defaults to current ``ipmi_username`` in
|
|
||||||
node ``driver_info`` field.
|
|
||||||
|
|
||||||
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/<UUID>`` 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)
|
|
||||||
* ``error`` error string or ``null``
|
|
||||||
|
|
||||||
Get Introspection Data
|
|
||||||
~~~~~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
``GET /v1/introspection/<UUID>/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
|
|
||||||
|
|
||||||
Introspection Rules
|
|
||||||
~~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
See `Introspection Rules documentation`_ 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 `Introspection Rules documentation`_
|
|
||||||
* ``actions`` rule actions, see `Introspection Rules documentation`_
|
|
||||||
* ``description`` (optional) human-readable description
|
|
||||||
* ``uuid`` (optional) rule UUID, autogenerated if missing
|
|
||||||
|
|
||||||
Response
|
|
||||||
|
|
||||||
* 200 - OK
|
|
||||||
* 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
|
|
||||||
|
|
||||||
.. _Introspection Rules documentation: https://github.com/openstack/ironic-inspector#introspection-rules
|
|
||||||
|
|
||||||
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:
|
|
||||||
|
|
||||||
* ``cpus`` number of CPU
|
|
||||||
* ``cpu_arch`` architecture of the CPU
|
|
||||||
* ``memory_mb`` RAM in MiB
|
|
||||||
* ``local_gb`` hard drive size in GiB
|
|
||||||
* ``interfaces`` dictionary filled with data from all NIC's, keys being
|
|
||||||
interface names, values being dictionaries with keys:
|
|
||||||
|
|
||||||
* ``mac`` MAC address
|
|
||||||
* ``ip`` IP address
|
|
||||||
|
|
||||||
* ``ipmi_address`` IP address of BMC, may be missing on VM
|
|
||||||
* ``boot_interface`` optional 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``.
|
|
||||||
|
|
||||||
* ``error`` optional error happened during ramdisk run, interpreted by
|
|
||||||
``ramdisk_error`` plugin
|
|
||||||
|
|
||||||
* ``logs`` optional base64-encoded logs from the ramdisk
|
|
||||||
|
|
||||||
* ``block_devices`` optional block devices information for
|
|
||||||
``root_device_hint`` plugin, dictionary with keys:
|
|
||||||
|
|
||||||
* ``serials`` list of serial numbers of block devices.
|
|
||||||
|
|
||||||
.. note::
|
|
||||||
This list highly depends on enabled plugins, provided above are
|
|
||||||
expected keys for the default set of plugins. See 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. If `Setting IPMI Credentials`_ is requested,
|
|
||||||
body will contain the following keys:
|
|
||||||
|
|
||||||
* ``ipmi_setup_credentials`` boolean ``True``
|
|
||||||
* ``ipmi_username`` new IPMI user name
|
|
||||||
* ``ipmi_password`` new IPMI password
|
|
||||||
|
|
||||||
.. _Setting IPMI Credentials: https://github.com/openstack/ironic-inspector#setting-ipmi-credentials
|
|
||||||
.. _Plugins: https://github.com/openstack/ironic-inspector#plugins
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
API Discovery
|
|
||||||
~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
The API supports API discovery. You can query different parts of the API to
|
|
||||||
discover what other endpoints are avaliable.
|
|
||||||
|
|
||||||
* ``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.
|
|
3
doc/source/contributing.rst
Normal file
3
doc/source/contributing.rst
Normal file
@ -0,0 +1,3 @@
|
|||||||
|
.. _contributing_link:
|
||||||
|
|
||||||
|
.. include:: ../../CONTRIBUTING.rst
|
@ -1,3 +0,0 @@
|
|||||||
.. _contributing_link:
|
|
||||||
|
|
||||||
.. include:: ../../../CONTRIBUTING.rst
|
|
@ -1,3 +1,5 @@
|
|||||||
|
.. _api:
|
||||||
|
|
||||||
HTTP API
|
HTTP API
|
||||||
--------
|
--------
|
||||||
|
|
||||||
@ -9,7 +11,7 @@ Start Introspection
|
|||||||
|
|
||||||
``POST /v1/introspection/<UUID>`` initiate hardware introspection for node
|
``POST /v1/introspection/<UUID>`` initiate hardware introspection for node
|
||||||
``<UUID>``. All power management configuration for this node needs to be done
|
``<UUID>``. All power management configuration for this node needs to be done
|
||||||
prior to calling the endpoint (except when `Setting IPMI Credentials`_).
|
prior to calling the endpoint (except when :ref:`setting-ipmi-creds`).
|
||||||
|
|
||||||
Requires X-Auth-Token header with Keystone token for authentication.
|
Requires X-Auth-Token header with Keystone token for authentication.
|
||||||
|
|
||||||
@ -17,8 +19,8 @@ Optional parameters:
|
|||||||
|
|
||||||
* ``new_ipmi_password`` if set, **ironic-inspector** will try to set IPMI
|
* ``new_ipmi_password`` if set, **ironic-inspector** will try to set IPMI
|
||||||
password on the machine to this value. Power credentials validation will be
|
password on the machine to this value. Power credentials validation will be
|
||||||
skipped and manual power on will be required. See `Setting IPMI
|
skipped and manual power on will be required. See :ref:`setting-ipmi-creds`
|
||||||
credentials`_ for details.
|
for details.
|
||||||
|
|
||||||
* ``new_ipmi_username`` provides new IPMI user name in addition to password
|
* ``new_ipmi_username`` provides new IPMI user name in addition to password
|
||||||
set by ``new_ipmi_password``. Defaults to current ``ipmi_username`` in
|
set by ``new_ipmi_password``. Defaults to current ``ipmi_username`` in
|
||||||
@ -71,7 +73,7 @@ Response body: JSON dictionary with introspection data
|
|||||||
Introspection Rules
|
Introspection Rules
|
||||||
~~~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
See `Introspection Rules documentation`_ for details.
|
See :ref:`rules` for details.
|
||||||
|
|
||||||
All these API endpoints require X-Auth-Token header with Keystone token for
|
All these API endpoints require X-Auth-Token header with Keystone token for
|
||||||
authentication.
|
authentication.
|
||||||
@ -80,8 +82,8 @@ authentication.
|
|||||||
|
|
||||||
Request body: JSON dictionary with keys:
|
Request body: JSON dictionary with keys:
|
||||||
|
|
||||||
* ``conditions`` rule conditions, see `Introspection Rules documentation`_
|
* ``conditions`` rule conditions, see :ref:`rules`
|
||||||
* ``actions`` rule actions, see `Introspection Rules documentation`_
|
* ``actions`` rule actions, see :ref:`rules`
|
||||||
* ``description`` (optional) human-readable description
|
* ``description`` (optional) human-readable description
|
||||||
* ``uuid`` (optional) rule UUID, autogenerated if missing
|
* ``uuid`` (optional) rule UUID, autogenerated if missing
|
||||||
|
|
||||||
@ -130,8 +132,6 @@ authentication.
|
|||||||
* 204 - OK
|
* 204 - OK
|
||||||
* 404 - not found
|
* 404 - not found
|
||||||
|
|
||||||
.. _Introspection Rules documentation: https://github.com/openstack/ironic-inspector#introspection-rules
|
|
||||||
|
|
||||||
Ramdisk Callback
|
Ramdisk Callback
|
||||||
~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
@ -166,7 +166,8 @@ the ramdisk. Request body: JSON dictionary with at least these keys:
|
|||||||
|
|
||||||
.. note::
|
.. note::
|
||||||
This list highly depends on enabled plugins, provided above are
|
This list highly depends on enabled plugins, provided above are
|
||||||
expected keys for the default set of plugins. See Plugins_ for details.
|
expected keys for the default set of plugins. See :ref:`plugins`
|
||||||
|
for details.
|
||||||
|
|
||||||
.. note::
|
.. note::
|
||||||
This endpoint is not expected to be versioned, though versioning will work
|
This endpoint is not expected to be versioned, though versioning will work
|
||||||
@ -179,16 +180,13 @@ Response:
|
|||||||
* 403 - node is not on introspection
|
* 403 - node is not on introspection
|
||||||
* 404 - node cannot be found or multiple nodes found
|
* 404 - node cannot be found or multiple nodes found
|
||||||
|
|
||||||
Response body: JSON dictionary. If `Setting IPMI Credentials`_ is requested,
|
Response body: JSON dictionary. If :ref:`setting-ipmi-creds` is requested,
|
||||||
body will contain the following keys:
|
body will contain the following keys:
|
||||||
|
|
||||||
* ``ipmi_setup_credentials`` boolean ``True``
|
* ``ipmi_setup_credentials`` boolean ``True``
|
||||||
* ``ipmi_username`` new IPMI user name
|
* ``ipmi_username`` new IPMI user name
|
||||||
* ``ipmi_password`` new IPMI password
|
* ``ipmi_password`` new IPMI password
|
||||||
|
|
||||||
.. _Setting IPMI Credentials: https://github.com/openstack/ironic-inspector#setting-ipmi-credentials
|
|
||||||
.. _Plugins: https://github.com/openstack/ironic-inspector#plugins
|
|
||||||
|
|
||||||
Error Response
|
Error Response
|
||||||
~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~
|
||||||
|
|
||||||
@ -269,6 +267,6 @@ discover what other endpoints are avaliable.
|
|||||||
Version History
|
Version History
|
||||||
^^^^^^^^^^^^^^^
|
^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
**1.0** version of API at the moment of introducing versioning.
|
* **1.0** version of API at the moment of introducing versioning.
|
||||||
**1.1** adds endpoint to retrieve stored introspection data.
|
* **1.1** adds endpoint to retrieve stored introspection data.
|
||||||
**1.2** endpoints for manipulating introspection rules.
|
* **1.2** endpoints for manipulating introspection rules.
|
@ -1,69 +1,31 @@
|
|||||||
Hardware introspection for OpenStack Bare Metal
|
.. include:: ../../README.rst
|
||||||
===============================================
|
|
||||||
|
|
||||||
This is an auxiliary service for discovering hardware properties for a
|
User Guide
|
||||||
node managed by `Ironic`_. Hardware introspection or hardware
|
===========
|
||||||
properties discovery is a process of getting hardware parameters required for
|
|
||||||
scheduling from a bare metal node, given it's power management credentials
|
|
||||||
(e.g. IPMI address, user name and password).
|
|
||||||
|
|
||||||
A special ramdisk is required to collect the information on a
|
.. toctree::
|
||||||
node. The default one can be built using diskimage-builder_ and
|
:maxdepth: 2
|
||||||
`ironic-discoverd-ramdisk element`_ (see :ref:`install_guide`).
|
|
||||||
|
|
||||||
* Free software: Apache license
|
Workflow <workflow>
|
||||||
* Source: http://git.openstack.org/cgit/openstack/ironic-inspector
|
Usage <usage>
|
||||||
* Bugs: http://bugs.launchpad.net/ironic-inspector
|
HTTP API <http-api>
|
||||||
* Blueprints: https://blueprints.launchpad.net/ironic-inspector
|
Troubleshooting <troubleshooting>
|
||||||
* Downloads: https://pypi.python.org/pypi/ironic-inspector
|
|
||||||
* Python client library and CLI tool: `python-ironic-inspector-client
|
|
||||||
<https://pypi.python.org/pypi/python-ironic-inspector-client>`_.
|
|
||||||
|
|
||||||
.. _Ironic: https://wiki.openstack.org/wiki/Ironic
|
|
||||||
.. _PyPI: https://pypi.python.org/pypi/ironic-inspector
|
|
||||||
.. _diskimage-builder: https://github.com/openstack/diskimage-builder
|
|
||||||
.. _ironic-discoverd-ramdisk element: https://github.com/openstack/diskimage-builder/tree/master/elements/ironic-discoverd-ramdisk
|
|
||||||
|
|
||||||
.. note::
|
|
||||||
**ironic-inspector** was called *ironic-discoverd* before version 2.0.0.
|
|
||||||
|
|
||||||
For information on any current or prior version, see `the release
|
|
||||||
notes`_ and `the wiki pages`_.
|
|
||||||
|
|
||||||
.. _the release notes: releasenotes/index.html
|
|
||||||
.. _the wiki pages: https://wiki.openstack.org/wiki/Ironic/ReleaseNotes
|
|
||||||
|
|
||||||
Admin Guide
|
Admin Guide
|
||||||
===========
|
===========
|
||||||
|
|
||||||
Overview
|
|
||||||
--------
|
|
||||||
|
|
||||||
.. toctree::
|
.. toctree::
|
||||||
:maxdepth: 1
|
:maxdepth: 2
|
||||||
|
|
||||||
Installation Guide <deploy/install-guide>
|
Installation <install>
|
||||||
Usage <usage/usage>
|
|
||||||
Troubleshooting <troubleshooting/troubleshooting>
|
|
||||||
|
|
||||||
Developer Guide
|
Developer Guide
|
||||||
===============
|
===============
|
||||||
|
|
||||||
Introduction
|
|
||||||
------------
|
|
||||||
|
|
||||||
.. toctree::
|
.. toctree::
|
||||||
:maxdepth: 1
|
:maxdepth: 1
|
||||||
|
|
||||||
Contribution Guide <dev/contributing_link>
|
Contributing <contributing>
|
||||||
|
|
||||||
API References
|
|
||||||
--------------
|
|
||||||
|
|
||||||
.. toctree::
|
|
||||||
:maxdepth: 1
|
|
||||||
|
|
||||||
HTTP API description <api/HTTP-API>
|
|
||||||
|
|
||||||
Indices and tables
|
Indices and tables
|
||||||
==================
|
==================
|
||||||
|
@ -9,13 +9,39 @@ environment)::
|
|||||||
pip install ironic-inspector
|
pip install ironic-inspector
|
||||||
|
|
||||||
Also there is a `DevStack <http://docs.openstack.org/developer/devstack/>`_
|
Also there is a `DevStack <http://docs.openstack.org/developer/devstack/>`_
|
||||||
plugin for **ironic-inspector** - see :ref:`contributing_link` for the current status.
|
plugin for **ironic-inspector** - see :ref:`contributing_link` for the current
|
||||||
|
status.
|
||||||
|
|
||||||
Finally, some distributions (e.g. Fedora) provide **ironic-inspector**
|
Finally, some distributions (e.g. Fedora) provide **ironic-inspector**
|
||||||
packaged, some of them - under its old name *ironic-discoverd*.
|
packaged, some of them - under its old name *ironic-discoverd*.
|
||||||
|
|
||||||
.. _PyPI: https://pypi.python.org/pypi/ironic-inspector
|
.. _PyPI: https://pypi.python.org/pypi/ironic-inspector
|
||||||
|
|
||||||
|
Version Support Matrix
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
**ironic-inspector** currently requires bare metal API version ``1.6`` to be
|
||||||
|
provided by Ironic. This version is available starting with Ironic Kilo
|
||||||
|
release.
|
||||||
|
|
||||||
|
Here is a mapping between Ironic versions and supported **ironic-inspector**
|
||||||
|
versions. The Standalone column shows which **ironic-inspector** versions can
|
||||||
|
be used in standalone mode with each Ironic version. The Inspection Interface
|
||||||
|
column shows which **ironic-inspector** versions can be used with the Ironic
|
||||||
|
inspection interface in each version of Ironic.
|
||||||
|
|
||||||
|
============== ========== ====================
|
||||||
|
Ironic Version Standalone Inspection Interface
|
||||||
|
============== ========== ====================
|
||||||
|
Juno 1.0 N/A
|
||||||
|
Kilo 1.0 - 2.2 1.0 - 1.1
|
||||||
|
Liberty 1.1 - 2.X 2.0 - 2.X
|
||||||
|
============== ========== ====================
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
``2.X`` means we don't have specific plans on deprecating support for this
|
||||||
|
Ironic version. This does not imply that we'll support it forever though.
|
||||||
|
|
||||||
Configuration
|
Configuration
|
||||||
~~~~~~~~~~~~~
|
~~~~~~~~~~~~~
|
||||||
|
|
||||||
@ -219,7 +245,7 @@ If you are upgrading from **ironic-inspector** version 2.1.0 or lower:
|
|||||||
ironic-inspector-dbsync --config-file /etc/ironic-inspector/inspector.conf upgrade
|
ironic-inspector-dbsync --config-file /etc/ironic-inspector/inspector.conf upgrade
|
||||||
|
|
||||||
If you are upgrading from a git master install of **ironic-inspector** from
|
If you are upgrading from a git master install of **ironic-inspector** from
|
||||||
after :ref:`introspection_rules` were introduced:
|
after :ref:`rules` were introduced:
|
||||||
::
|
::
|
||||||
|
|
||||||
ironic-inspector-dbsync --config-file /etc/ironic-inspector/inspector.conf stamp --revision d588418040d
|
ironic-inspector-dbsync --config-file /etc/ironic-inspector/inspector.conf stamp --revision d588418040d
|
@ -1,13 +1,12 @@
|
|||||||
|
.. _usage:
|
||||||
|
|
||||||
Usage
|
Usage
|
||||||
=====
|
=====
|
||||||
|
|
||||||
|
Refer to :ref:`api` for information on the HTTP API.
|
||||||
Refer to HTTP-API.rst_ for information on the HTTP API.
|
|
||||||
Refer to the `client page`_ for information on how to use CLI and Python
|
Refer to the `client page`_ for information on how to use CLI and Python
|
||||||
library.
|
library.
|
||||||
|
|
||||||
.. _HTTP-API.rst: https://github.com/openstack/ironic-inspector/blob/master/HTTP-API.rst
|
|
||||||
.. _HTTP API: https://github.com/openstack/ironic-inspector/blob/master/HTTP-API.rst
|
|
||||||
.. _client page: https://pypi.python.org/pypi/python-ironic-inspector-client
|
.. _client page: https://pypi.python.org/pypi/python-ironic-inspector-client
|
||||||
|
|
||||||
Using from Ironic API
|
Using from Ironic API
|
||||||
@ -39,7 +38,7 @@ Node States
|
|||||||
before Nova becomes aware of available nodes after issuing this command.
|
before Nova becomes aware of available nodes after issuing this command.
|
||||||
Use ``nova hypervisor-stats`` command output to check it.
|
Use ``nova hypervisor-stats`` command output to check it.
|
||||||
|
|
||||||
.. _introspection_rules:
|
.. _rules:
|
||||||
|
|
||||||
Introspection Rules
|
Introspection Rules
|
||||||
~~~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~~~
|
||||||
@ -54,8 +53,8 @@ All actions have "rollback actions" associated with them, which are run when
|
|||||||
conditions evaluate to false. This way we can safely rerun introspection.
|
conditions evaluate to false. This way we can safely rerun introspection.
|
||||||
|
|
||||||
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 `HTTP API`_ for specific calls to define
|
see :ref:`contributing_link` for details. See :ref:`api` for specific calls
|
||||||
introspection rules.
|
to define introspection rules.
|
||||||
|
|
||||||
Conditions
|
Conditions
|
||||||
^^^^^^^^^^
|
^^^^^^^^^^
|
||||||
@ -105,6 +104,8 @@ Default available actions include:
|
|||||||
value as a list and appends value to it. If optional ``unique`` parameter is
|
value as a list and appends value to it. If optional ``unique`` parameter is
|
||||||
set to ``True``, nothing will be added if given value is already in a list.
|
set to ``True``, nothing will be added if given value is already in a list.
|
||||||
|
|
||||||
|
.. _setting-ipmi-creds:
|
||||||
|
|
||||||
Setting IPMI Credentials
|
Setting IPMI Credentials
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
@ -149,6 +150,8 @@ Note that due to various limitations on password value in different BMC,
|
|||||||
**ironic-inspector** will only accept passwords with length between 1 and 20
|
**ironic-inspector** will only accept passwords with length between 1 and 20
|
||||||
consisting only of letters and numbers.
|
consisting only of letters and numbers.
|
||||||
|
|
||||||
|
.. _plugins:
|
||||||
|
|
||||||
Plugins
|
Plugins
|
||||||
~~~~~~~
|
~~~~~~~
|
||||||
|
|
||||||
@ -162,7 +165,7 @@ unless you understand what you're doing:
|
|||||||
|
|
||||||
``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 `HTTP API`_ for details.
|
stores logs from ``logs`` field, see :ref:`api` for details.
|
||||||
``scheduler``
|
``scheduler``
|
||||||
validates and updates basic hardware scheduling properties: CPU number and
|
validates and updates basic hardware scheduling properties: CPU number and
|
||||||
architecture, memory and disk size.
|
architecture, memory and disk size.
|
||||||
@ -184,4 +187,5 @@ Here are some plugins that can be additionally enabled:
|
|||||||
then deleted from the introspection data, as unless converted it's assumed
|
then deleted from the introspection data, as unless converted it's assumed
|
||||||
unusable by introspection rules.
|
unusable by introspection rules.
|
||||||
|
|
||||||
Refer to :ref:`contributing_link` for information on how to write your own plugin.
|
Refer to :ref:`contributing_link` for information on how to write your
|
||||||
|
own plugin.
|
61
doc/source/workflow.rst
Normal file
61
doc/source/workflow.rst
Normal file
@ -0,0 +1,61 @@
|
|||||||
|
Workflow
|
||||||
|
========
|
||||||
|
|
||||||
|
Usual hardware introspection flow is as follows:
|
||||||
|
|
||||||
|
* Operator enrolls nodes into Ironic_ e.g. via ironic CLI command.
|
||||||
|
Power management credentials should be provided to Ironic at this step.
|
||||||
|
|
||||||
|
* Nodes are put in the correct state for introspection as described in
|
||||||
|
:ref:`node_states`.
|
||||||
|
|
||||||
|
* Operator sends nodes on introspection using **ironic-inspector** API or CLI
|
||||||
|
(see :ref:`usage`).
|
||||||
|
|
||||||
|
* On receiving node UUID **ironic-inspector**:
|
||||||
|
|
||||||
|
* validates node power credentials, current power and provisioning states,
|
||||||
|
* allows firewall access to PXE boot service for the nodes,
|
||||||
|
* issues reboot command for the nodes, so that they boot the ramdisk.
|
||||||
|
|
||||||
|
* The ramdisk collects the required information and posts it back to
|
||||||
|
**ironic-inspector**.
|
||||||
|
|
||||||
|
* On receiving data from the ramdisk, **ironic-inspector**:
|
||||||
|
|
||||||
|
* validates received data,
|
||||||
|
* finds the node in Ironic database using it's BMC address (MAC address in
|
||||||
|
case of SSH driver),
|
||||||
|
* fills missing node properties with received data and creates missing ports.
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
**ironic-inspector** is responsible to create Ironic ports for some or all
|
||||||
|
NIC's found on the node. **ironic-inspector** is also capable of
|
||||||
|
deleting ports that should not be present. There are two important
|
||||||
|
configuration options that affect this behavior: ``add_ports`` and
|
||||||
|
``keep_ports`` (please refer to ``example.conf`` for detailed explanation).
|
||||||
|
|
||||||
|
Default values as of **ironic-inspector** 1.1.0 are ``add_ports=pxe``,
|
||||||
|
``keep_ports=all``, which means that only one port will be added, which is
|
||||||
|
associated with NIC the ramdisk PXE booted from. No ports will be deleted.
|
||||||
|
This setting ensures that deploying on introspected nodes will succeed
|
||||||
|
despite `Ironic bug 1405131
|
||||||
|
<https://bugs.launchpad.net/ironic/+bug/1405131>`_.
|
||||||
|
|
||||||
|
Ironic inspection feature by default requires different settings:
|
||||||
|
``add_ports=all``, ``keep_ports=present``, which means that ports will be
|
||||||
|
created for all detected NIC's, and all other ports will be deleted.
|
||||||
|
Refer to the `Ironic inspection documentation`_ for details.
|
||||||
|
|
||||||
|
* Separate API (see :ref:`usage` and :ref:`api`) can be used to query
|
||||||
|
introspection results for a given node.
|
||||||
|
|
||||||
|
* Nodes are put in the correct state for deploying as described in
|
||||||
|
:ref:`node_states`.
|
||||||
|
|
||||||
|
Starting DHCP server and configuring PXE boot environment is not part of this
|
||||||
|
package and should be done separately.
|
||||||
|
|
||||||
|
.. _Ironic inspection documentation: http://docs.openstack.org/developer/ironic/deploy/install-guide.html#hardware-inspection
|
||||||
|
.. _Ironic: https://wiki.openstack.org/wiki/Ironic
|
||||||
|
|
@ -71,3 +71,6 @@ output_file = ironic-inspector/locale/ironic-inspector.pot
|
|||||||
all_files = 1
|
all_files = 1
|
||||||
build-dir = doc/build
|
build-dir = doc/build
|
||||||
source-dir = doc/source
|
source-dir = doc/source
|
||||||
|
|
||||||
|
[pbr]
|
||||||
|
warnerrors = True
|
||||||
|
2
tox.ini
2
tox.ini
@ -28,7 +28,7 @@ commands =
|
|||||||
basepython = python2.7
|
basepython = python2.7
|
||||||
commands =
|
commands =
|
||||||
flake8 ironic_inspector
|
flake8 ironic_inspector
|
||||||
doc8 README.rst CONTRIBUTING.rst HTTP-API.rst
|
doc8 README.rst CONTRIBUTING.rst doc/source
|
||||||
|
|
||||||
[testenv:func]
|
[testenv:func]
|
||||||
basepython = python2.7
|
basepython = python2.7
|
||||||
|
Loading…
Reference in New Issue
Block a user