ironic/doc/source/admin/inspection/migration.rst

Migrating from ironic-inspector

This document outlines the process of migrating from a separate ironic-inspector service to the built-in 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.

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
• discovery is no longer based on plug-ins.
• Introspection of nodes in the active provision state.
• PXE filters based on iptables.
• Certain client commands are not available in ironicclient, for example, the ones that display the network interface information from the LLDP data.

Inspection rules <user/usage.html#introspection-rules> have now been implemented as of 2025.1 "Epoxy" release.

New defaults

• The database :oslo.configdata storage backend <inventory.data_backend> is used by default.
• The list of :oslo.configdefault hooks <inspector.default_hooks> is limited to only most commonly used ones (see also Built-in hooks).

Built-in hooks

Most of the introspection hooks <user/usage.html#plugins> have been migrated to ironic <hooks>, although many have been migrated for clarity and consistency.

Hooks mapping

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.

Custom hooks

A custom hook (called processing hook in ironic-inspector) has to be derived from the base class :pyInspectionHook <ironic.drivers.modules.inspector.hooks.base.InspectionHook>. It differs from the older 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 :pytask <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. For migration of data between Swift buckets, you could adapt copy-inspection-data-swift.

Migration process

1. Make sure you're running at ironic 2024.1 or newer.

2. Enable the new inspection implementation as described in index.

3. Carefully research options in the :oslo.configinventory and :oslo.configinspector 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, configure unmanaged boot <configure-unmanaged-inspection>.

6. If using the OpenStack Networking, consider configuring (but not starting yet) the 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 pxe_filter if needed. Restart the Bare Metal service.

10. Change all nodes to use the new inspection interface, for example:

    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

11. Make sure your scripts use ironicclient and the Bare Metal API in OpenStackSDK instead of the client API that is specific to ironic-inspector.