How it works¶
Integration with Ironic¶
For information on how to install and configure Ironic drivers, including drivers for IPA, see the Ironic drivers documentation.
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.
After successfully looking up its node, the agent heartbeats via
every N seconds, where N is the Ironic conductor’s
value multiplied by a number between .3 and .6.
For example, if your conductor’s ironic.conf contains:
[agent] heartbeat_timeout = 60
IPA will heartbeat between every 20 and 36 seconds. This is to ensure jitter for any agents reconnecting after a network or API disruption.
After the agent heartbeats, the conductor performs any actions needed against the node, including querying status of an already run command. For example, initiating in-band cleaning tasks or deploying an image to the node.
Edit your default PXE/iPXE configuration or IPA options baked in the image, and
ipa-inspection-callback-url to the full endpoint of Ironic Inspector,
Make sure your DHCP environment is set to boot IPA by default.
For the cases where the infrastructure operator and cloud user are the same,
an additional tool exists that can be installed alongside the agent inside
a running instance. This is the
command which allows for a node in
ACTIVE state to publish updated
introspection data to ironic-inspector. This ability requires ironic-inspector
to be configured with
[processing]permit_active_introspection set to
True. For example:
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:
ironic-collect-introspection-data --inspection_callback_url mdns
An additional daemon mode may be useful for some operators who wish to receive
regular updates, in the form of the
ironic-collect-introspection-data --inspection_callback_url mdns --introspection_daemon
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.
The exact format of the data depends on the enabled collectors, which can be
configured using the
ipa-inspection-collectors kernel parameter. Each
collector appends information to the resulting JSON object. The in-tree
The default enabled collectors. Collects the following keys:
inventory- Hardware Inventory.
root_disk- The default root device for this machine, which will be used for deployment if root device hints are not provided.
configuration- Inspection configuration, an object with two keys:
collectors- List of enabled collectors.
managers- List of enabled Hardware Managers: items with keys
boot_interface- Deprecated, use the
Collect system logs. To yield useful results it must always go last in the list of collectors. Provides one key:
logs- base64 encoded tarball with various logs.
Collects the list of PCI devices. Provides one key:
pci_devices- list of objects with keys
Collects a vast list of facts about the systems, using the hardware library, which is a required dependency for this collector. Adds one key:
data- raw data from the
hardware-collectutility. Is a list of lists with 4 items each. It is recommended to use this collector together with the
extra_hardwareprocessing hook on the Ironic Inspector side to convert it to a nested dictionary in the
ipa-inspection-benchmarksis set, the corresponding benchmarks are executed and their result is also provided.
Collects information from
dmidecode. Provides one key:
dmiDMI information in three keys:
Collects NUMA topology information. Provides one key:
numa_topologywith three nested keys:
ram- list of objects with keys
numa_node(node ID) and
cpus- list of objects with keys
numa_node(node ID) and
thread_siblings(list of sibling threads).
nics- list of objects with keys
name(NIC name) and
Collects information about the network connectivity using LLDP. Provides one key:
lldp_raw- mapping of interface names to lists of raw type-length-value (TLV) records.
The exact format of the inventory depends on the hardware manager used. Here is the basic format expected to be provided by all hardware managers. The inventory is a dictionary (JSON object), containing at least the following fields:
total(total size in bytes),
physical_mb(physically installed memory size in MiB, optional).
The difference is that the latter includes the memory region reserved by the kernel and is always slightly bigger. It also matches what the Nova flavor would contain for this node and thus is used by the inspection process instead of
IPv4 address of the node’s BMC (aka IPMI v4 address), optional.
IPv6 address of the node’s BMC (aka IPMI v6 address), optional.
list of disk block devices with fields:
by_path(the full disk path, in the form
list of network interfaces with fields:
product, and optionally
biosdevname(BIOS given NIC name) and
speed_mbps(maximum supported speed).
For backward compatibility, interfaces may contain
lldpfields. They are deprecated, consumers should rely on the
lldpinspection collector instead.
system vendor information from SMBIOS as reported by
manufacturer, as well as a
firmwarestructure with fields
boot information with fields:
current_boot_mode(boot mode used for the current boot - BIOS or UEFI) and
pxe_interface(interface used for PXE booting, if any).
hostname for the system
This is most likely to be set by the DHCP server. Could be localhost if the DHCP server does not set it.
As part of the process of downloading images to be written to disk as part of
image deployment, a series of fields are utilized to determine if the
image which has been downloaded matches what the user stated as the expected
image checksum utilizing the
OpenStack, as a whole, has replaced the “legacy”
checksum field with
os_hash_algo fields, which allows for an image
checksum and value to be asserted. An advantage of this is a variety of
algorithms are available, if a user/operator is so-inclined.
For the purposes of Ironic, we continue to support the pass-through checksum field as we support the checksum being retrieved via a URL.
We also support determining the checksum by length.
The field can be utilized to designate:
A URL to retreive a checksum from.
MD5 (Disabled by default, see
[DEFAULT]md5_enabledin the agent configuration file.)
SHA-2 based SHA256
SHA-2 based SHA512
SHA-3 based checksums are not supported for auto-determination as they can
have a variable length checksum result. At of when this documentation was
added, SHA-2 based checksum algorithms have not been withdrawn from from
approval. If you need to force use of SHA-3 based checksums, you must
os_hash_algo setting along with the