Browse Source

docs: use openstackdocstheme extlink extension

The extlink extension [1] ensures the urls have version-specific
references to other projects.

[1] https://docs.openstack.org/openstackdocstheme/latest/#external-link-helper

Change-Id: I59ae4e28a02ee2683d35cf46857386e3f458ec2c
Story: 2006621
Task: 36917
changes/62/686562/5
Riccardo Pittau 3 years ago
parent
commit
aa75bfa8f0
  1. 9
      doc/source/admin/dnsmasq-pxe-filter.rst
  2. 10
      doc/source/conf.py
  3. 31
      doc/source/install/index.rst
  4. 15
      doc/source/user/http-api.rst
  5. 4
      doc/source/user/troubleshooting.rst
  6. 12
      doc/source/user/usage.rst
  7. 10
      doc/source/user/workflow.rst

9
doc/source/admin/dnsmasq-pxe-filter.rst

@ -82,9 +82,10 @@ commands to, for instance, directly control the **dnsmasq** service::
.. note::
These commands are executed through the rootwrap_ facility, so overriding
may require a filter file to be created in the ``rootwrap.d`` directory. A
sample configuration to use with the **systemctl** facility might be:
These commands are executed through the :oslo.rootwrap-doc:`rootwrap <>`
facility, so overriding may require a filter file to be created in the
``rootwrap.d`` directory. A sample configuration to use with the
**systemctl** facility might be:
.. code-block:: console
@ -95,8 +96,6 @@ commands to, for instance, directly control the **dnsmasq** service::
systemctl: CommandFilter, systemctl, root, stop, dnsmasq
EOF
.. _rootwrap: https://docs.openstack.org/oslo.rootwrap/latest/
Caveats
-------

10
doc/source/conf.py

@ -21,6 +21,16 @@ except ImportError:
repository_name = 'openstack/ironic-inspector'
use_storyboard = True
openstack_projects = [
'bifrost',
'devstack',
'ironic',
'ironic-python-agent',
'oslo.rootwrap',
'python-ironicclient',
'python-ironic-inspector-client',
'tooz',
]
wsme_protocols = ['restjson']

31
doc/source/install/index.rst

@ -6,19 +6,17 @@ environment)::
pip install ironic-inspector
Also there is a `DevStack <https://docs.openstack.org/devstack/latest/>`_
plugin for **ironic-inspector** - see :ref:`contributing_link` for the
current status.
Also there is a :devstack-doc:`DevStack <>` 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*.
There are several projects you can use to set up **ironic-inspector** in
production. `puppet-ironic
<https://git.openstack.org/cgit/openstack/puppet-ironic/>`_ provides Puppet
manifests, while `bifrost <https://docs.openstack.org/bifrost/latest/>`_
provides an Ansible-based standalone installer. Refer to Configuration_
if you plan on installing **ironic-inspector** manually.
production. `puppet-ironic <https://git.openstack.org/cgit/openstack/puppet-ironic/>`_
provides Puppet manifests, while :bifrost-doc:`bifrost <>` provides an
Ansible-based standalone installer. Refer to Configuration_ if you plan on
installing **ironic-inspector** manually.
.. _PyPI: https://pypi.org/project/ironic-inspector
@ -90,7 +88,7 @@ non-standalone mode:
is configured to use ``etcd3+http://``, ``pymemcache`` is required to use
``memcached://``. Some distributions may provide packages like
``python3-etcd3gw`` or ``python3-memcache``. Supported drivers are listed at
`Tooz drivers <https://docs.openstack.org/tooz/latest/user/drivers.html>`_.
:tooz-doc:`Tooz drivers <user/drivers.html>`.
* For ironic-inspector running in non-standalone mode, PXE configuration is
only required on the node where ironic-inspector conductor service is
@ -228,9 +226,9 @@ Replace ``stack`` with whatever user you'll be using to run
Configuring IPA
~~~~~~~~~~~~~~~
ironic-python-agent_ is a ramdisk developed for **ironic** and support
for **ironic-inspector** was added during the Liberty cycle. This is the
default ramdisk starting with the Mitaka release.
:ironic-python-agent-doc:`ironic-python-agent <>` is a ramdisk developed for
**ironic** and support for **ironic-inspector** was added during the Liberty
cycle. This is the default ramdisk starting with the Mitaka release.
.. note::
You need at least 1.5 GiB of RAM on the machines to use IPA built with
@ -254,11 +252,10 @@ To build an **ironic-python-agent** ramdisk, do the following:
Alternatively, you can download a `prebuilt TinyIPA image
<https://tarballs.openstack.org/ironic-python-agent/tinyipa/files/>`_ or use
the `other builders
<https://docs.openstack.org/ironic-python-agent/latest/install/index.html#image-builders>`_.
the :ironic-python-agent-doc:`other builders
<install/index.html#image-builders>`.
.. _diskimage-builder: https://docs.openstack.org/diskimage-builder/latest/
.. _ironic-python-agent: https://docs.openstack.org/ironic-python-agent/latest/
Configuring PXE
~~~~~~~~~~~~~~~
@ -472,7 +469,9 @@ service. Below is a sample configuration for Apache with module mod_wsgi::
</Directory>
</VirtualHost>
You can refer to `ironic installation document <https://docs.openstack.org/ironic/latest/install/install-rdo.html#configuring-ironic-api-behind-mod-wsgi>`_
You can refer to
:ironic-doc:`ironic installation document
<install/install-rdo.html#configuring-ironic-api-behind-mod-wsgi>`
for more guides.
ironic-inspector conductor can be started with::

15
doc/source/user/http-api.rst

@ -227,8 +227,10 @@ Ramdisk Callback
discovered data. Should not be used for anything other than implementing
the ramdisk. Request body: JSON dictionary with at least these keys:
* ``inventory`` full `hardware inventory`_ from the ironic-python-agent with at
least the following keys:
* ``inventory`` full
:ironic-python-agent-doc:`hardware inventory
<admin/how_it_works.html#hardware-inventory>`
from the ironic-python-agent with at least the following keys:
* ``memory`` memory information containing at least key ``physical_mb`` -
physical memory size as reported by dmidecode,
@ -258,8 +260,9 @@ the ramdisk. Request body: JSON dictionary with at least these keys:
.. note::
**ironic-inspector** default plugin ``root_disk_selection`` may change
``root_disk`` based on root device hints if node specify hints via
properties ``root_device`` key. See `Specifying the disk for deployment
root device hints`_ for more details.
properties ``root_device`` key. See
:ironic-doc:`Specifying the disk for deployment root device hints <install/advanced.html#specifying-the-disk-for-deployment-root-device-hints>`
for more details.
* ``boot_interface`` MAC address of the NIC that the machine PXE booted from
either in standard format ``11:22:33:44:55:66`` or in *PXELinux* ``BOOTIF``
@ -291,10 +294,6 @@ Response:
Response body: JSON dictionary with ``uuid`` key.
.. _hardware inventory: https://docs.openstack.org/ironic-python-agent/latest/admin/how_it_works.html#hardware-inventory
.. _Specifying the disk for deployment root device hints:
https://docs.openstack.org/ironic/latest/install/advanced.html#specifying-the-disk-for-deployment-root-device-hints
Error Response
~~~~~~~~~~~~~~

4
doc/source/user/troubleshooting.rst

@ -22,8 +22,8 @@ There may be 3 reasons why introspection can time out after some time
#. Fatal failure in processing chain before node was found in the local cache.
See `Troubleshooting data processing`_ for the hints.
#. Failure to load the ramdisk on the target node. See `Troubleshooting
PXE boot`_ for the hints.
#. Failure to load the ramdisk on the target node. See
`Troubleshooting PXE boot`_ for the hints.
#. Failure during ramdisk run. See `Troubleshooting ramdisk run`_ for the
hints.

12
doc/source/user/usage.rst

@ -4,19 +4,17 @@ Usage
.. _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.
.. _client documentation: https://docs.openstack.org/python-ironic-inspector-client/latest/
Refer to the :python-ironic-inspector-client-doc:`client documentation <>`
for information on how to use CLI and Python library.
Using from Ironic API
~~~~~~~~~~~~~~~~~~~~~
Ironic Kilo introduced support for hardware introspection under name of
"inspection". **ironic-inspector** introspection is supported for some generic
drivers, please refer to `Ironic inspection documentation`_ for details.
.. _Ironic inspection documentation: https://docs.openstack.org/ironic/latest/admin/inspection.html
drivers, please refer to
:ironic-doc:`Ironic inspection documentation <admin/inspection.html>`
for details.
Node States
~~~~~~~~~~~

10
doc/source/user/workflow.rst

@ -6,7 +6,8 @@ Workflow
Usual hardware introspection flow is as follows:
* Operator enrolls nodes into Ironic_ e.g. via `openstack baremetal CLI`_
* Operator enrolls nodes into Ironic_ e.g. via
:python-ironicclient-doc:`openstack baremetal CLI <cli/osc_plugin_cli.html>`
command. Power management credentials should be provided to Ironic at this
step.
@ -50,15 +51,15 @@ Usual hardware introspection flow is as follows:
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.
Refer to the
:ironic-doc:`Ironic inspection documentation <admin/inspection.html>`
for details.
Ironic inspector can also be configured to not create any ports. This is
done by setting ``add_ports=disabled``. If setting ``add_ports`` to disabled
the ``keep_ports`` option should be also set to ``all``. This will ensure
no manually added ports will be deleted.
.. _Ironic inspection documentation: https://docs.openstack.org/ironic/latest/admin/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.
@ -83,4 +84,3 @@ The diagram also shows events that trigger state transitions.
:alt: ironic-inspector state machine diagram
.. _Ironic: https://wiki.openstack.org/wiki/Ironic
.. _openstack baremetal CLI: https://docs.openstack.org/python-ironicclient/latest/cli/osc_plugin_cli.html

Loading…
Cancel
Save