Documentation: migration guide from inspector

Change-Id: I622085adc431555789921f04b5ba2375f806075e

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
 -------------

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 <index>`.
+
+.. 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
+  <https://docs.openstack.org/api-ref/baremetal-introspection/#get-unprocessed-introspection-data>`_
+* `Reapplying the processing pipeline on new data
+  <https://docs.openstack.org/api-ref/baremetal-introspection/#reapply-introspection-on-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 <user/usage.html#introspection-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
+  <inventory.data_backend>` is used by default.
+* The list of :oslo.config:option:`default hooks <inspector.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
+<user/usage.html#plugins>` have been :doc:`migrated to ironic <hooks>`,
+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
+<ironic.drivers.modules.inspector.hooks.base.InspectionHook>`. It differs
+from the older :ironic-inspector-doc:`ProcessingHook
+<contributor/api/ironic_inspector.plugins.base.html#ironic_inspector.plugins.base.ProcessingHook>`
+in a few important ways, requiring custom hooks to be adapted for ironic:
+
+* Hooks operate on the regular :py:class:`task
+  <ironic.conductor.task_manager.TaskManager>` 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 <configure-unmanaged-inspection>`.
+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

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