From a88cc4d9de2dee3121c86c5f700bc896233623a7 Mon Sep 17 00:00:00 2001 From: Dmitry Tantsur Date: Mon, 17 Jun 2024 13:28:06 +0200 Subject: [PATCH] Documentation: migration guide from inspector Change-Id: I622085adc431555789921f04b5ba2375f806075e --- doc/source/admin/inspection/index.rst | 2 + doc/source/admin/inspection/migration.rst | 164 ++++++++++++++++++++++ doc/source/conf.py | 4 + 3 files changed, 170 insertions(+) create mode 100644 doc/source/admin/inspection/migration.rst diff --git a/doc/source/admin/inspection/index.rst b/doc/source/admin/inspection/index.rst index d27fe174c0..aa2e3700ce 100644 --- a/doc/source/admin/inspection/index.rst +++ b/doc/source/admin/inspection/index.rst @@ -22,12 +22,14 @@ ironic-inspector_ service. .. _ironic-inspector: https://pypi.org/project/ironic-inspector .. toctree:: + :maxdepth: 2 managed data hooks discovery pxe_filter + migration Configuration ------------- diff --git a/doc/source/admin/inspection/migration.rst b/doc/source/admin/inspection/migration.rst new file mode 100644 index 0000000000..1713d0d470 --- /dev/null +++ b/doc/source/admin/inspection/migration.rst @@ -0,0 +1,164 @@ +Migrating from ironic-inspector +=============================== + +This document outlines the process of migrating from a separate +ironic-inspector_ service to the built-in :doc:`in-band inspection `. + +.. note:: + This is a live document that is updated as more ironic-inspector features + are supported in ironic. If you're upgrading to a branch other than + ``master``, use the version of this document from the target branch. + +.. _ironic-inspector: https://docs.openstack.org/ironic-inspector/ + +Understand the feature differences +---------------------------------- + +Removed +~~~~~~~ + +Some rarely used or controversial features have not been migrated to ironic. +This list currently includes: + +* `Retrieving unprocesses inspection data + `_ +* `Reapplying the processing pipeline on new data + `_ +* :doc:`discovery` is no longer based on plug-ins. +* Introspection of nodes in the ``active`` provision state. +* PXE filters based on ``iptables`` + +:ironic-inspector-doc:`Inspection rules ` +are also currently not implemented but are planned for the 2024.2 release or +later. + +New defaults +~~~~~~~~~~~~ + +* The database :oslo.config:option:`data storage backend + ` is used by default. +* The list of :oslo.config:option:`default hooks ` is + limited to only most commonly used ones (see also `Built-in hooks`_). + +Built-in hooks +~~~~~~~~~~~~~~ + +Most of the :ironic-inspector-doc:`introspection hooks +` have been :doc:`migrated to ironic `, +although many have been migrated for clarity and consistency. + +.. list-table:: Hooks mapping + :header-rows: 1 + + * - Inspector + - ironic + - ``default_hooks``? + - Notes + * - ``accelerators`` + - ``accelerators`` + - No + - + * - ``capabilities`` + - ``boot-mode``, ``cpu-capabilities`` + - No + - Split into two logical parts. + * - ``extra_hardware`` + - ``extra-hardware`` + - No + - python-hardware_ is not actively maintained any more. + * - ``lldp_basic`` + - ``parse-lldp`` + - No + - + * - ``local_link_connection`` + - ``local-link-connection`` + - No + - + * - ``pci_devices`` + - ``pci-devices`` + - No + - + * - ``physnet_cidr_map`` + - ``physical-network`` + - No + - + * - ``raid_device`` + - ``raid-device`` + - No + - + * - ``root_device`` + - ``root-device`` + - No + - + * - ``ramdisk_error`` + - ``ramdisk-error`` + - **Yes** + - + * - ``scheduler`` + - ``architecture``, ``memory`` + - Only ``architecture`` + - Split, dropped ``local_gb`` and ``vcpus`` support. + * - ``validate_interfaces`` + - ``validate-interfaces``, ``ports`` + - **Yes** + - Split into two logical parts. + +.. _python-hardware: https://github.com/redhat-cip/hardware + +Custom hooks +~~~~~~~~~~~~ + +A custom hook (called *processing hook* in ironic-inspector) has to be +derived from the base class :py:class:`InspectionHook +`. It differs +from the older :ironic-inspector-doc:`ProcessingHook +` +in a few important ways, requiring custom hooks to be adapted for ironic: + +* Hooks operate on the regular :py:class:`task + ` instead of the + inspector-specific ``NodeInfo`` object. +* Since changes to nodes and ports no longer require an API call, hooks are + expected to commit their changes immediately rather than letting them + accumulate on the task object. +* The hook methods have been renamed: ``before_processing`` is called + ``preprocess``, the ``__call__`` method is used instead of + ``before_update``. +* *Introspection data* has been split into its *inventory* part and *plugin + data*. Hooks should not update the inventory. +* New hooks use the entry point ``ironic.inspection.hooks`` instead of + ``ironic_inspector.hooks.processing``. + +Other concerns +~~~~~~~~~~~~~~ + +* There is no way to migrate the inspection data automatically. You need to + repeat inspections or copy the data over manually. + +Migration process +----------------- + +1. Make sure you're running at ironic 2024.1 or newer. +2. Enable the new inspection implementation as described in :doc:`index`. +3. Carefully research options in the :oslo.config:group:`inventory` and + :oslo.config:group:`inspector` sections. Update options to match similar + ones in the ironic-inspector configuration. +4. Enable the required `Built-in hooks`_, taking into the account the new names + and composition. +5. If using network boot and *unmanaged* inspection or auto-discovery, + :ref:`configure unmanaged boot `. +6. If using the OpenStack Networking, consider configuring (but not starting + yet) the :doc:`pxe_filter`. +7. Make sure no inspection are running. +8. Stop ironic-inspector or at least disable its PXE filter (it may conflict + with the one used here). +9. Start :doc:`pxe_filter` if needed. Restart the Bare Metal service. +10. Change all nodes to use the new inspection interface, for example: + + .. code-block:: bash + + baremetal node list --fields uuid inspect_interface -f value | while read uuid iface; do + if [ "$iface" = "inspector" ]; then + baremetal node set --inspect-interface agent "$uuid" + fi + done diff --git a/doc/source/conf.py b/doc/source/conf.py index 21c606b5fe..b3a3aa367b 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -57,6 +57,10 @@ apidoc_excluded_paths = [ ] apidoc_separate_modules = True +autodoc_default_options = { + 'special-members': '__call__', +} + openstackdocs_repo_name = 'openstack/ironic' openstackdocs_use_storyboard = False openstackdocs_pdf_link = True