openstack/ironic-python-agent
Code Issues Proposed changes

Refactor and fix documentation

Browse Source 
Currently the index page contains a brief introduction and 3 links.
Expand the table of contents to show more subheadings.

Clean up the install, admin and contributing docs of unnecessary
and wrong content and redundant headings.

Update URLs throughout the text.

Change-Id: I03279ffc9faf387b08f727dee3b8898a69918460
This commit is contained in:
Dmitry Tantsur 2020-08-24 15:02:30 +02:00
parent a8b865de9e
commit 3faf13bbb4
9 changed files with 49 additions and 115 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

64
doc/source/admin/how_it_works.rst
View File

@ -3,39 +3,24 @@ How it works
Integration with Ironic
-----------------------
Compatible Deploy Drivers
~~~~~~~~~~~~~~~~~~~~~~~~~
Agent Deploy Driver
<<<<<<<<<<<<<<<<<<<
IPA works with the agent Deploy driver in Ironic to provision nodes. Starting
with ironic-python-agent running on a ramdisk on an unprovisioned node,
Ironic makes API calls to ironic-python-agent to provision the machine. This
allows for greater control and flexibility of the entire deployment process.
PXE Deploy Driver
<<<<<<<<<<<<<<<<<
IPA may also be used with the original Ironic pxe driver as of the Kilo
OpenStack Ironic release.
Configuring Deploy Drivers
<<<<<<<<<<<<<<<<<<<<<<<<<<
For information on how to install and configure Ironic drivers, including
drivers for IPA, see the Ironic drivers documentation [0]_.
drivers for IPA, see the :ironic-doc:`Ironic drivers documentation
</admin/drivers/ipa.html>`.
Lookup
~~~~~~
On startup, the agent performs a lookup in Ironic to determine its node UUID
by sending a hardware profile to the Ironic lookup endpoint:
``/v1/lookup``.
`/v1/lookup
<https://docs.openstack.org/api-ref/baremetal/?expanded=agent-lookup-detail#agent-lookup>`_.
Heartbeat
~~~~~~~~~
After successfully looking up its node, the agent heartbeats via
``/v1/heartbeat/{node_ident}`` every N seconds, where
N is the Ironic conductor's agent.heartbeat_timeout value multiplied by a
number between .3 and .6.
`/v1/heartbeat/{node_ident}
<https://docs.openstack.org/api-ref/baremetal/?expanded=agent-heartbeat-detail#agent-heartbeat>`_
every N seconds, where N is the Ironic conductor's ``agent.heartbeat_timeout``
value multiplied by a number between .3 and .6.
For example, if your conductor's ironic.conf contains::
@ -50,11 +35,15 @@ the node, including querying status of an already run command. For example,
initiating in-band cleaning tasks or deploying an image to the node.
Inspection
~~~~~~~~~~
IPA can conduct hardware inspection on start up and post data to the `Ironic
Inspector`_. Edit your default PXE/iPXE configuration or IPA options
baked in the image, and set ``ipa-inspection-callback-url`` to the
full endpoint of Ironic Inspector, for example::
----------
IPA can conduct hardware inspection on start up and post data to the
:ironic-inspector-doc:`Ironic Inspector <>` via the `/v1/continue
<https://docs.openstack.org/api-ref/baremetal-introspection/?expanded=ramdisk-callback-detail#ramdisk-callback>`_
endpoint.
Edit your default PXE/iPXE configuration or IPA options baked in the image, and
set ``ipa-inspection-callback-url`` to the full endpoint of Ironic Inspector,
for example::
ipa-inspection-callback-url=http://IP:5050/v1/continue
@ -71,8 +60,7 @@ to be configured with ``[processing]permit_active_introspection`` set to
ironic-collect-introspection-data --inspection_callback_url http://IP:5050/v1/continue
Alternatively, this command may also be used with multicast DNS
functionality to identify the `Ironic Inspector`_ service endpoint.
For example::
functionality to identify the Ironic Inspector service endpoint. For example::
ironic-collect-introspection-data --inspection_callback_url mdns
@ -87,13 +75,12 @@ The above command will attempt to connect to introspection and will then enter
a loop to publish every 300 seconds. This can be tuned with the
``[DEFAULT]introspection_daemon_post_interval`` configuration option.
.. _Ironic Inspector: https://docs.openstack.org/ironic-inspector/
Inspection Data
<<<<<<<<<<<<<<<
~~~~~~~~~~~~~~~
As part of the inspection process, data is collected on the machine and sent
back to `Ironic Inspector`_ for storage. It can be accessed via the
`introspection data API`_.
back to :ironic-inspector-doc:`Ironic Inspector <>` for storage. It can be
accessed via the `introspection data API
<https://docs.openstack.org/api-ref/baremetal-introspection/?expanded=get-introspection-data-detail#get-introspection-data>`_.
The exact format of the data depends on the enabled *collectors*, which can be
configured using the ``ipa-inspection-collectors`` kernel parameter. Each
@ -133,7 +120,7 @@ collectors are:
* ``data`` - raw data from the ``hardware-collect`` utility. Is a list of
lists with 4 items each. It is recommended to use this collector together
with the ``extra_hardware`` processing hook on the `Ironic Inspector`_
with the ``extra_hardware`` processing hook on the Ironic Inspector
side to convert it to a nested dictionary in the ``extra`` key.
If ``ipa-inspection-benchmarks`` is set, the corresponding benchmarks are
@ -158,7 +145,6 @@ collectors are:
* ``nics`` - list of objects with keys ``name`` (NIC name) and
``numa_node`` (node ID).
.. _introspection data API: https://docs.openstack.org/ironic-inspector/latest/user/http-api.html#get-introspection-data
.. _hardware: https://pypi.org/project/hardware/
.. _NUMA: https://en.wikipedia.org/wiki/Non-uniform_memory_access
@ -223,7 +209,3 @@ fields:
.. note::
This is most likely to be set by the DHCP server. Could be localhost
if the DHCP server does not set it.
References
==========
.. [0] Enabling Drivers - https://docs.openstack.org/ironic/latest/admin/drivers/ipa.html

19
doc/source/admin/index.rst
View File

@ -2,26 +2,7 @@
Ironic Python Agent Administration
==================================
Overview
========
Ironic Python Agent is an agent for controlling and deploying Ironic controlled
baremetal nodes. Typically run in a ramdisk, the agent exposes a REST API for
provisioning servers.
Throughout the documentation, Ironic Python Agent will be
abbreviated to IPA.
Index
=====
.. toctree::
how_it_works
rescue
troubleshooting
Indices and tables
==================
* :ref:`genindex`
* :ref:`search`

2
doc/source/admin/rescue.rst
View File

@ -47,4 +47,4 @@ After the ``finalize_rescue`` command completes, DHCP will be configured on all
network interfaces, and a `rescue` user will be created with the specified
``rescue_password``.
.. _`build a TinyIPA image`: https://opendev.org/openstack/ironic-python-agent-builder/src/branch/master/tinyipa/README.rst
.. _build a TinyIPA image: https://docs.openstack.org/ironic-python-agent-builder/latest/admin/tinyipa.html

5
doc/source/conf.py
View File

@ -8,6 +8,11 @@ extensions = ['sphinx.ext.autodoc',
'openstackdocstheme',
]
openstackdocs_projects = [
'ironic',
'ironic-inspector',
]
# autodoc generation is a bit aggressive and a nuisance when doing heavy
# text edit cycles.
# execute "export SPHINX_DEBUG=1" in your terminal to disable

20
doc/source/contributor/hardware_managers.rst
View File

@ -3,12 +3,13 @@
Hardware Managers
=================
What is a HardwareManager?
--------------------------
Hardware managers are how IPA supports multiple different hardware platforms
in the same agent. Any action performed on hardware can be overridden by
deploying your own hardware manager.
IPA ships with GenericHardwareManager, which implements basic cleaning and
deployment methods compatible with most hardware.
How are methods executed on HardwareManagers?
---------------------------------------------
Methods that modify hardware are dispatched to each hardware manager in
@ -20,11 +21,6 @@ passed on to whatever dispatched the method. If the method is unable to run
successfully on any hardware managers, `HardwareManagerMethodNotFound` is
raised.
Does IPA ship with a HardwareManager?
-------------------------------------
IPA ships with GenericHardwareManager, which implements basic cleaning and
deployment methods compatible with most hardware.
Why build a custom HardwareManager?
-----------------------------------
Custom hardware managers allow you to include hardware-specific tools, files
@ -54,9 +50,9 @@ and adapter for your use case.
Custom HardwareManagers and Cleaning
------------------------------------
One of the reasons to build a custom hardware manager is to expose extra steps
in Ironic Cleaning [1]_. A node will perform a set of cleaning steps any
time the node is deleted by a tenant or moved from MANAGEABLE state to
AVAILABLE state. If the node is using an agent\_\* driver, Ironic will query
in :ironic-doc:`Ironic Cleaning </admin/cleaning.html>`. A node will perform
a set of cleaning steps any time the node is deleted by a tenant or moved from
``manageable`` state to ``available`` state. Ironic will query
IPA for a list of clean steps that should be executed on the node. IPA
will dispatch a call to `get_clean_steps()` on all available hardware managers
and then return the combined list to Ironic.
@ -133,7 +129,3 @@ about the platform it's running on. Suggested values are included in the
will prevent the hardware manager from being used. IPA will never ship a
hardware manager with a priority higher than 3, aka
`HardwareSupport.SERVICE_PROVIDER`.
References
==========
.. [1] Ironic Cleaning - https://docs.openstack.org/ironic/latest/admin/cleaning.html

18
doc/source/contributor/index.rst
View File

@ -1,9 +1,6 @@
====================================
Contributing to Ironic Python Agent!
====================================
Overview
========
===================================
Contributing to Ironic Python Agent
===================================
Ironic Python Agent is an agent for controlling and deploying Ironic controlled
baremetal nodes. Typically run in a ramdisk, the agent exposes a REST API for
@ -12,9 +9,6 @@ provisioning servers.
Throughout the remainder of the document, Ironic Python Agent will be
abbreviated to IPA.
Index
=====
.. toctree::
hardware_managers
@ -30,9 +24,3 @@ Generated Developer Documentation
:hidden:
api/modules
Indices and tables
==================
* :ref:`genindex`
* :ref:`search`

2
doc/source/contributor/rescue.rst
View File

@ -1,5 +1,3 @@
.. rescue:
===========
Rescue Mode
===========

12
doc/source/index.rst
View File

@ -5,15 +5,15 @@ Welcome to Ironic Python Agent!
Overview
========
Ironic Python Agent is an agent for controlling and deploying Ironic controlled
baremetal nodes. Typically run in a ramdisk, the agent exposes a REST API for
provisioning servers.
Ironic Python Agent (often abbreviated as IPA) is an agent for controlling and
deploying :ironic-doc:`Ironic <>` controlled baremetal nodes. Typically run in
a ramdisk, the agent exposes a REST API for provisioning servers.
Index
=====
Contents
========
.. toctree::
:maxdepth: 1
:maxdepth: 3
install/index
admin/index

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

@ -1,6 +1,6 @@
===============================
Installing Ironic Python Agent!
===============================
==============================
Installing Ironic Python Agent
==============================
Image Builders
==============
@ -106,14 +106,10 @@ ramdisk builds.
Hardware Managers
=================
What is a HardwareManager?
--------------------------
Hardware managers are how IPA supports multiple different hardware platforms
in the same agent. Any action performed on hardware can be overridden by
deploying your own hardware manager.
Why build a custom HardwareManager?
-----------------------------------
Custom hardware managers allow you to include hardware-specific tools, files
and cleaning steps in the Ironic Python Agent. For example, you could include a
BIOS flashing utility and BIOS file in a custom ramdisk. Your custom
@ -121,18 +117,10 @@ hardware manager could expose a cleaning step that calls the flashing utility
and flashes the packaged BIOS version (or even download it from a tested web
server).
How can I build a custom HardwareManager?
-----------------------------------------
Operators wishing to build their own hardware managers should reference
the documentation available at `Hardware Managers`_.
the documentation available at :doc:`Hardware Managers
</contributor/hardware_managers>`.
.. _Hardware Managers: https://docs.openstack.org/ironic-python-agent/latest/contributor/hardware_managers.html
.. _ironic-python-agent-builder: https://docs.openstack.org/ironic-python-agent-builder
.. _DIB: https://docs.openstack.org/ironic-python-agent-builder/latest/admin/dib.html
.. _TinyIPA: https://docs.openstack.org/ironic-python-agent-builder/latest/admin/tinyipa.html
Indices and tables
==================
* :ref:`genindex`
* :ref:`search`