From 99732e5297244f9209061d6e9ac74153c1d4e71b Mon Sep 17 00:00:00 2001 From: Dmitry Tantsur Date: Wed, 2 Dec 2015 17:57:58 +0100 Subject: [PATCH] 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 --- README.rst | 103 +------ doc/source/api/HTTP-API.rst | 274 ------------------ doc/source/contributing.rst | 3 + doc/source/dev/contributing_link.rst | 3 - HTTP-API.rst => doc/source/http-api.rst | 30 +- doc/source/index.rst | 62 +--- .../{deploy/install-guide.rst => install.rst} | 30 +- .../{troubleshooting => }/troubleshooting.rst | 0 doc/source/{usage => }/usage.rst | 22 +- doc/source/workflow.rst | 61 ++++ setup.cfg | 3 + tox.ini | 2 +- 12 files changed, 137 insertions(+), 456 deletions(-) delete mode 100644 doc/source/api/HTTP-API.rst create mode 100644 doc/source/contributing.rst delete mode 100644 doc/source/dev/contributing_link.rst rename HTTP-API.rst => doc/source/http-api.rst (87%) rename doc/source/{deploy/install-guide.rst => install.rst} (88%) rename doc/source/{troubleshooting => }/troubleshooting.rst (100%) rename doc/source/{usage => }/usage.rst (93%) create mode 100644 doc/source/workflow.rst diff --git a/README.rst b/README.rst index 73a9c0251..caedd1168 100644 --- a/README.rst +++ b/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 (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 * Source: http://git.openstack.org/cgit/openstack/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 `_. -Refer to CONTRIBUTING.rst_ for instructions on how to contribute. - .. _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:: **ironic-inspector** was called *ironic-discoverd* before version 2.0.0. -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| 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 - `_. - - 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 +For information on any current or prior version, see `the release notes`_. +.. _the release notes: http://docs.openstack.org/releasenotes/ironic-inspector/ diff --git a/doc/source/api/HTTP-API.rst b/doc/source/api/HTTP-API.rst deleted file mode 100644 index 363e683e7..000000000 --- a/doc/source/api/HTTP-API.rst +++ /dev/null @@ -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/`` initiate hardware introspection for node -````. 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/`` 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//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/`` get one introspection rule by its ````. - - Response - - * 200 - OK - * 404 - not found - - Response body: JSON dictionary with introspection rule representation - (see ``POST /v1/rules`` above). - -* ``DELETE /v1/rules/`` delete one introspection rule by its ````. - - 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. diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst new file mode 100644 index 000000000..e9e65340a --- /dev/null +++ b/doc/source/contributing.rst @@ -0,0 +1,3 @@ +.. _contributing_link: + +.. include:: ../../CONTRIBUTING.rst diff --git a/doc/source/dev/contributing_link.rst b/doc/source/dev/contributing_link.rst deleted file mode 100644 index f4e26a51c..000000000 --- a/doc/source/dev/contributing_link.rst +++ /dev/null @@ -1,3 +0,0 @@ -.. _contributing_link: - -.. include:: ../../../CONTRIBUTING.rst \ No newline at end of file diff --git a/HTTP-API.rst b/doc/source/http-api.rst similarity index 87% rename from HTTP-API.rst rename to doc/source/http-api.rst index 363e683e7..b0c6ff048 100644 --- a/HTTP-API.rst +++ b/doc/source/http-api.rst @@ -1,3 +1,5 @@ +.. _api: + HTTP API -------- @@ -9,7 +11,7 @@ Start Introspection ``POST /v1/introspection/`` initiate hardware introspection for node ````. 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. @@ -17,8 +19,8 @@ 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. + skipped and manual power on will be required. See :ref:`setting-ipmi-creds` + 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 @@ -71,7 +73,7 @@ Response body: JSON dictionary with introspection data 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 authentication. @@ -80,8 +82,8 @@ authentication. Request body: JSON dictionary with keys: - * ``conditions`` rule conditions, see `Introspection Rules documentation`_ - * ``actions`` rule actions, see `Introspection Rules documentation`_ + * ``conditions`` rule conditions, see :ref:`rules` + * ``actions`` rule actions, see :ref:`rules` * ``description`` (optional) human-readable description * ``uuid`` (optional) rule UUID, autogenerated if missing @@ -130,8 +132,6 @@ authentication. * 204 - OK * 404 - not found -.. _Introspection Rules documentation: https://github.com/openstack/ironic-inspector#introspection-rules - Ramdisk Callback ~~~~~~~~~~~~~~~~ @@ -166,7 +166,8 @@ the ramdisk. Request body: JSON dictionary with at least these keys: .. note:: 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:: This endpoint is not expected to be versioned, though versioning will work @@ -179,16 +180,13 @@ Response: * 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, +Response body: JSON dictionary. If :ref:`setting-ipmi-creds` 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 ~~~~~~~~~~~~~~ @@ -269,6 +267,6 @@ discover what other endpoints are avaliable. 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.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. diff --git a/doc/source/index.rst b/doc/source/index.rst index 1c2315e45..79bf990d5 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -1,69 +1,31 @@ -Hardware introspection for OpenStack Bare Metal -=============================================== +.. include:: ../../README.rst -This is an auxiliary service for discovering hardware properties for a -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). +User Guide +=========== -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 :ref:`install_guide`). +.. toctree:: + :maxdepth: 2 -* Free software: Apache license -* Source: http://git.openstack.org/cgit/openstack/ironic-inspector -* Bugs: http://bugs.launchpad.net/ironic-inspector -* Blueprints: https://blueprints.launchpad.net/ironic-inspector -* Downloads: https://pypi.python.org/pypi/ironic-inspector -* Python client library and CLI tool: `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 + Workflow + Usage + HTTP API + Troubleshooting Admin Guide =========== -Overview --------- - .. toctree:: - :maxdepth: 1 + :maxdepth: 2 - Installation Guide - Usage - Troubleshooting + Installation Developer Guide =============== -Introduction ------------- - .. toctree:: :maxdepth: 1 - Contribution Guide - -API References --------------- - -.. toctree:: - :maxdepth: 1 - - HTTP API description + Contributing Indices and tables ================== diff --git a/doc/source/deploy/install-guide.rst b/doc/source/install.rst similarity index 88% rename from doc/source/deploy/install-guide.rst rename to doc/source/install.rst index bd319f46c..8e5f4fb8b 100644 --- a/doc/source/deploy/install-guide.rst +++ b/doc/source/install.rst @@ -9,13 +9,39 @@ environment):: pip install ironic-inspector Also there is a `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** packaged, some of them - under its old name *ironic-discoverd*. .. _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 ~~~~~~~~~~~~~ @@ -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 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 diff --git a/doc/source/troubleshooting/troubleshooting.rst b/doc/source/troubleshooting.rst similarity index 100% rename from doc/source/troubleshooting/troubleshooting.rst rename to doc/source/troubleshooting.rst diff --git a/doc/source/usage/usage.rst b/doc/source/usage.rst similarity index 93% rename from doc/source/usage/usage.rst rename to doc/source/usage.rst index 9f666c341..c14325beb 100644 --- a/doc/source/usage/usage.rst +++ b/doc/source/usage.rst @@ -1,13 +1,12 @@ +.. _usage: + Usage ===== - -Refer to HTTP-API.rst_ for information on the HTTP API. +Refer to :ref:`api` for information on the HTTP API. Refer to the `client page`_ for information on how to use CLI and Python 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 Using from Ironic API @@ -39,7 +38,7 @@ Node States before Nova becomes aware of available nodes after issuing this command. Use ``nova hypervisor-stats`` command output to check it. -.. _introspection_rules: +.. _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. 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 -introspection rules. +see :ref:`contributing_link` for details. See :ref:`api` for specific calls +to define introspection rules. Conditions ^^^^^^^^^^ @@ -105,6 +104,8 @@ Default available actions include: 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. +.. _setting-ipmi-creds: + 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 consisting only of letters and numbers. +.. _plugins: + Plugins ~~~~~~~ @@ -162,7 +165,7 @@ unless you understand what you're doing: ``ramdisk_error`` 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`` validates and updates basic hardware scheduling properties: CPU number and 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 unusable by introspection rules. -Refer to :ref:`contributing_link` for information on how to write your own plugin. \ No newline at end of file +Refer to :ref:`contributing_link` for information on how to write your +own plugin. diff --git a/doc/source/workflow.rst b/doc/source/workflow.rst new file mode 100644 index 000000000..3061b44b2 --- /dev/null +++ b/doc/source/workflow.rst @@ -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 + `_. + + 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 + diff --git a/setup.cfg b/setup.cfg index e96361674..26cf1ad7d 100644 --- a/setup.cfg +++ b/setup.cfg @@ -71,3 +71,6 @@ output_file = ironic-inspector/locale/ironic-inspector.pot all_files = 1 build-dir = doc/build source-dir = doc/source + +[pbr] +warnerrors = True diff --git a/tox.ini b/tox.ini index 57a42804b..500673fa1 100644 --- a/tox.ini +++ b/tox.ini @@ -28,7 +28,7 @@ commands = basepython = python2.7 commands = flake8 ironic_inspector - doc8 README.rst CONTRIBUTING.rst HTTP-API.rst + doc8 README.rst CONTRIBUTING.rst doc/source [testenv:func] basepython = python2.7