From 3faf13bbb4eff5d8d3760040ad8e1d92617048f1 Mon Sep 17 00:00:00 2001 From: Dmitry Tantsur Date: Mon, 24 Aug 2020 15:02:30 +0200 Subject: [PATCH] Refactor and fix documentation 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 --- doc/source/admin/how_it_works.rst | 64 +++++++------------- doc/source/admin/index.rst | 19 ------ doc/source/admin/rescue.rst | 2 +- doc/source/conf.py | 5 ++ doc/source/contributor/hardware_managers.rst | 20 ++---- doc/source/contributor/index.rst | 18 +----- doc/source/contributor/rescue.rst | 2 - doc/source/index.rst | 12 ++-- doc/source/install/index.rst | 22 ++----- 9 files changed, 49 insertions(+), 115 deletions(-) diff --git a/doc/source/admin/how_it_works.rst b/doc/source/admin/how_it_works.rst index 05bbd1a4e..191f0a1b9 100644 --- a/doc/source/admin/how_it_works.rst +++ b/doc/source/admin/how_it_works.rst @@ -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 +`. 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 +`_. 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} +`_ +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 +`_ +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 +`_. 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 diff --git a/doc/source/admin/index.rst b/doc/source/admin/index.rst index dbe5cdd07..a7e4bf1a3 100644 --- a/doc/source/admin/index.rst +++ b/doc/source/admin/index.rst @@ -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` diff --git a/doc/source/admin/rescue.rst b/doc/source/admin/rescue.rst index f4e351f05..8e8084266 100644 --- a/doc/source/admin/rescue.rst +++ b/doc/source/admin/rescue.rst @@ -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 diff --git a/doc/source/conf.py b/doc/source/conf.py index f64921bb0..ef07ac124 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -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 diff --git a/doc/source/contributor/hardware_managers.rst b/doc/source/contributor/hardware_managers.rst index 282acd5b3..b1f4daef6 100644 --- a/doc/source/contributor/hardware_managers.rst +++ b/doc/source/contributor/hardware_managers.rst @@ -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 `. 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 diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst index bba5cbb3b..cff7ff76e 100644 --- a/doc/source/contributor/index.rst +++ b/doc/source/contributor/index.rst @@ -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` diff --git a/doc/source/contributor/rescue.rst b/doc/source/contributor/rescue.rst index 934da8b6d..e89194385 100644 --- a/doc/source/contributor/rescue.rst +++ b/doc/source/contributor/rescue.rst @@ -1,5 +1,3 @@ -.. rescue: - =========== Rescue Mode =========== diff --git a/doc/source/index.rst b/doc/source/index.rst index 2303716a5..131c0d457 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -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 diff --git a/doc/source/install/index.rst b/doc/source/install/index.rst index 12cbff866..21fdd1d75 100644 --- a/doc/source/install/index.rst +++ b/doc/source/install/index.rst @@ -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 +`. -.. _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`