openstack/ironic-inspector
Code Issues Proposed changes

Merge "Introducing the user content"

Browse Source
This commit is contained in:
Jenkins 2017-07-25 16:02:11 +00:00 committed by Gerrit Code Review
commit 2ba104cc54
8 changed files with 94 additions and 59 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
CONTRIBUTING.rst
View File

@ -69,7 +69,7 @@ To run the functional tests, use::
tox -e func
Once you have added new state or transition into inspection state machine, you
should regenerate :ref:`state_machine_diagram` with::
should regenerate :ref:`State machine diagram <state_machine_diagram>` with::
tox -e genstates

19
doc/source/index.rst
View File

@ -1,16 +1,5 @@
.. include:: ../../README.rst
User Guide
===========
.. toctree::
:maxdepth: 2
Workflow <workflow>
Usage <usage>
HTTP API <http-api>
Troubleshooting <troubleshooting>
Install
=======
@ -28,6 +17,14 @@ Contributor
contributor/index
User
====
.. toctree::
:maxdepth: 2
user/index
Indices and tables
==================

2
doc/source/install/index.rst
View File

@ -339,7 +339,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
If you are upgrading from a git master install of the **ironic-inspector**
after :ref:`rules` were introduced:
after :ref:`rules <introspection_rules>` were introduced:
::
ironic-inspector-dbsync --config-file /etc/ironic-inspector/inspector.conf stamp --revision d588418040d

18
doc/source/http-api.rst → doc/source/user/http-api.rst
View File

@ -1,8 +1,8 @@
.. _api:
HTTP API
--------
.. _http_api:
By default **ironic-inspector** listens on ``0.0.0.0:5050``, port
can be changed in configuration. Protocol is JSON over HTTP.
@ -153,7 +153,7 @@ Response:
Introspection Rules
~~~~~~~~~~~~~~~~~~~
See :ref:`rules` for details.
See :ref:`rules <introspection_rules>` for details.
All these API endpoints require X-Auth-Token header with Keystone token for
authentication.
@ -162,8 +162,8 @@ authentication.
Request body: JSON dictionary with keys:
* ``conditions`` rule conditions, see :ref:`rules`
* ``actions`` rule actions, see :ref:`rules`
* ``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
@ -213,11 +213,11 @@ authentication.
* 204 - OK
* 404 - not found
.. _ramdisk_callback:
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:
@ -270,8 +270,8 @@ Optionally the following keys might be provided:
.. note::
This list highly depends on enabled plugins, provided above are
expected keys for the default set of plugins. See :ref:`plugins`
for details.
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

34
doc/source/user/index.rst Normal file
View File

@ -0,0 +1,34 @@
User Guide
==========
How Ironic Inspector Works
--------------------------
.. toctree::
:maxdepth: 2
workflow
How to use Ironic Inspector
---------------------------
.. toctree::
:maxdepth: 2
usage
HTTP API Reference
------------------
.. toctree::
:maxdepth: 2
http-api
Troubleshooting
---------------
.. toctree::
:maxdepth: 2
troubleshooting

18
doc/source/troubleshooting.rst → doc/source/user/troubleshooting.rst
View File

@ -1,17 +1,17 @@
Troubleshooting
===============
---------------
Errors when starting introspection
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* *Invalid provision state "available"*
In Kilo release with *python-ironicclient* 0.5.0 or newer Ironic
defaults to reporting provision state ``AVAILABLE`` for newly enrolled
nodes. **ironic-inspector** will refuse to conduct introspection in
this state, as such nodes are supposed to be used by Nova for scheduling.
See :ref:`node_states` for instructions on how to put nodes into
the correct state.
In Kilo release with *python-ironicclient* 0.5.0 or newer Ironic defaults to
reporting provision state ``AVAILABLE`` for newly enrolled nodes.
**ironic-inspector** will refuse to conduct introspection in this state, as
such nodes are supposed to be used by Nova for scheduling. See :ref:`node
states <node_states>` for instructions on how to put nodes into the correct
state.
Introspection times out
~~~~~~~~~~~~~~~~~~~~~~~
@ -116,11 +116,11 @@ one.
.. _devuser: http://docs.openstack.org/developer/diskimage-builder/elements/devuser/README.html
.. _dynamic-login: http://docs.openstack.org/developer/diskimage-builder/elements/dynamic-login/README.html
.. _ubuntu-dns:
Troubleshooting DNS issues on Ubuntu
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. _ubuntu-dns:
Ubuntu uses local DNS caching, so tries localhost for DNS results first
before calling out to an external DNS server. When DNSmasq is installed and
configured for use with ironic-inspector, it can cause problems by interfering

34
doc/source/usage.rst → doc/source/user/usage.rst
View File

@ -1,9 +1,9 @@
.. _usage:
Usage
=====
-----
Refer to :ref:`api` for information on the HTTP API.
.. _usage_guide:
Refer to :ref:`api <http_api>` for information on the HTTP API.
Refer to the `client documentation`_ for information on how to use CLI and
Python library.
@ -18,11 +18,11 @@ drivers, please refer to `Ironic inspection documentation`_ for details.
.. _Ironic inspection documentation: http://docs.openstack.org/developer/ironic/deploy/inspection.html
.. _node_states:
Node States
~~~~~~~~~~~
.. _node_states:
* The nodes should be moved to ``MANAGEABLE`` provision state before
introspection (requires *python-ironicclient* of version 0.5.0 or newer)::
@ -38,11 +38,11 @@ Node States
before Nova becomes aware of available nodes after issuing this command.
Use ``nova hypervisor-stats`` command output to check it.
.. _rules:
Introspection Rules
~~~~~~~~~~~~~~~~~~~
.. _introspection_rules:
Inspector supports a simple JSON-based DSL to define rules to run during
introspection. Inspector provides an API to manage such rules, and will run
them automatically after running all processing hooks.
@ -51,8 +51,8 @@ A rule consists of conditions to check, and actions to run. If conditions
evaluate to true on the introspection data, then actions are run on a node.
Available conditions and actions are defined by plugins, and can be extended,
see :ref:`contributing_link` for details. See :ref:`api` for specific calls
to define introspection rules.
see :ref:`contributing_link` for details. See :ref:`api <http_api>` for
specific calls to define introspection rules.
Conditions
^^^^^^^^^^
@ -130,11 +130,11 @@ from introspection, it's using `python string formatting notation
{"action": "set-attribute", "path": "/driver_info/ipmi_address",
"value": "{data[inventory][bmc_address]}"}
.. _plugins:
Plugins
~~~~~~~
.. _introspection_plugins:
**ironic-inspector** heavily relies on plugins for data processing. Even the
standard functionality is largely based on plugins. Set ``processing_hooks``
option in the configuration file to change the set of plugins to be run on
@ -165,7 +165,7 @@ needed:
``ramdisk_error``
reports error, if ``error`` field is set by the ramdisk, also optionally
stores logs from ``logs`` field, see :ref:`api` for details.
stores logs from ``logs`` field, see :ref:`api <http_api>` for details.
``capabilities``
detect node capabilities: CPU, boot mode, etc. See `Capabilities
Detection`_ for more details.
@ -225,13 +225,13 @@ file, to the Ironic driver you want).
The ``enroll`` hook will also set the ``ipmi_address`` property on the new
node, if its available in the introspection data we received,
see :ref:`ramdisk_callback`.
see :ref:`ramdisk_callback <ramdisk_callback>`.
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
the processing :ref:`plugins`, and after that it runs introspection
rules, which would allow for more customisable node configuration,
see :ref:`rules`.
the processing :ref:`plugins <introspection_plugins>`, and after that it runs
introspection rules, which would allow for more customisable node
configuration, see :ref:`rules <introspection_rules>`.
A rule to set a node's Ironic driver to the ``agent_ipmitool`` driver and
populate the required driver_info for that driver would look like::

26
doc/source/workflow.rst → doc/source/user/workflow.rst
View File

@ -1,5 +1,8 @@
How Ironic Inspector Works
==========================
Workflow
========
--------
Usual hardware introspection flow is as follows:
@ -7,10 +10,10 @@ Usual hardware introspection flow is as follows:
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`.
:ref:`node states <node_states>`.
* Operator sends nodes on introspection using **ironic-inspector** API or CLI
(see :ref:`usage`).
(see :ref:`usage <usage_guide>`).
* On receiving node UUID **ironic-inspector**:
@ -52,28 +55,29 @@ Usual hardware introspection flow is as follows:
the ``keep_ports`` option should be also set to ``all``. This will ensure
no manually added ports will be deleted.
* Separate API (see :ref:`usage` and :ref:`api`) can be used to query
introspection results for a given node.
.. _Ironic inspection documentation: http://docs.openstack.org/developer/ironic/deploy/inspection.html
* Separate API (see :ref:`usage <usage_guide>` and :ref:`api <http_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`.
:ref:`node states <node_states>`.
Starting DHCP server and configuring PXE boot environment is not part of this
package and should be done separately.
.. _state_machine_diagram:
State machine diagram
=====================
---------------------
.. _state_machine_diagram:
The diagram below shows the introspection states that an **ironic-inspector**
FSM goes through during the node introspection, discovery and reprocessing.
The diagram also shows events that trigger state transitions.
.. figure:: ./images/states.svg
.. figure:: ../images/states.svg
:width: 660px
:align: center
:alt: ironic-inspector state machine diagram
.. _Ironic inspection documentation: https://docs.openstack.org/developer/ironic/deploy/inspection.html
.. _Ironic: https://wiki.openstack.org/wiki/Ironic