From c38ac86d53cf80576b46e477a637d5d75424e987 Mon Sep 17 00:00:00 2001 From: dparalen Date: Tue, 4 Jul 2017 17:42:41 +0200 Subject: [PATCH] Introducing the user content Moving the user content down the mandatory directory path. Change-Id: Icccf00cb22eab01c9ae7626f0997b9c362471e4d Partial-Bug: 1702142 --- CONTRIBUTING.rst | 2 +- doc/source/index.rst | 19 ++++++------- doc/source/install/index.rst | 2 +- doc/source/{ => user}/http-api.rst | 18 ++++++------ doc/source/user/index.rst | 34 +++++++++++++++++++++++ doc/source/{ => user}/troubleshooting.rst | 18 ++++++------ doc/source/{ => user}/usage.rst | 34 +++++++++++------------ doc/source/{ => user}/workflow.rst | 26 +++++++++-------- 8 files changed, 94 insertions(+), 59 deletions(-) rename doc/source/{ => user}/http-api.rst (97%) create mode 100644 doc/source/user/index.rst rename doc/source/{ => user}/troubleshooting.rst (94%) rename doc/source/{ => user}/usage.rst (96%) rename doc/source/{ => user}/workflow.rst (86%) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index c69f8cc90..bdeda711d 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -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 ` with:: tox -e genstates diff --git a/doc/source/index.rst b/doc/source/index.rst index b2a84e6be..f23ce7969 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -1,16 +1,5 @@ .. include:: ../../README.rst -User Guide -=========== - -.. toctree:: - :maxdepth: 2 - - Workflow - Usage - HTTP API - Troubleshooting - Install ======= @@ -28,6 +17,14 @@ Contributor contributor/index +User +==== + +.. toctree:: + :maxdepth: 2 + + user/index + Indices and tables ================== diff --git a/doc/source/install/index.rst b/doc/source/install/index.rst index 2aeca2013..37409cc31 100644 --- a/doc/source/install/index.rst +++ b/doc/source/install/index.rst @@ -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 ` were introduced: :: ironic-inspector-dbsync --config-file /etc/ironic-inspector/inspector.conf stamp --revision d588418040d diff --git a/doc/source/http-api.rst b/doc/source/user/http-api.rst similarity index 97% rename from doc/source/http-api.rst rename to doc/source/user/http-api.rst index c51b07002..4a99f2c81 100644 --- a/doc/source/http-api.rst +++ b/doc/source/user/http-api.rst @@ -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 ` 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 ` + * ``actions`` rule actions, see :ref:`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 ` for details. .. note:: This endpoint is not expected to be versioned, though versioning will work diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst new file mode 100644 index 000000000..260076b94 --- /dev/null +++ b/doc/source/user/index.rst @@ -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 diff --git a/doc/source/troubleshooting.rst b/doc/source/user/troubleshooting.rst similarity index 94% rename from doc/source/troubleshooting.rst rename to doc/source/user/troubleshooting.rst index c05eb0234..337564bd0 100644 --- a/doc/source/troubleshooting.rst +++ b/doc/source/user/troubleshooting.rst @@ -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 ` 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 diff --git a/doc/source/usage.rst b/doc/source/user/usage.rst similarity index 96% rename from doc/source/usage.rst rename to doc/source/user/usage.rst index a09d2c983..7cccc238e 100644 --- a/doc/source/usage.rst +++ b/doc/source/user/usage.rst @@ -1,9 +1,9 @@ -.. _usage: - Usage -===== +----- -Refer to :ref:`api` for information on the HTTP API. +.. _usage_guide: + +Refer to :ref:`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 ` 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 ` 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 `. 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 `, and after that it runs +introspection rules, which would allow for more customisable node +configuration, see :ref:`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:: diff --git a/doc/source/workflow.rst b/doc/source/user/workflow.rst similarity index 86% rename from doc/source/workflow.rst rename to doc/source/user/workflow.rst index fe629cf6a..0cf5b100c 100644 --- a/doc/source/workflow.rst +++ b/doc/source/user/workflow.rst @@ -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 `. * Operator sends nodes on introspection using **ironic-inspector** API or CLI - (see :ref:`usage`). + (see :ref:`usage `). * 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 ` 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`. + :ref:`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