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`