Images built using diskimage-builder are recommended for production use on real hardware. The recommended distributions are:
CentOS Stream 9
Debian Bookworm (
The following should work but receive only limited testing and support:
Ubuntu 20.04 Focal
Debian Bullseye (
… with the helper script¶
To build an image using
ironic-python-agent-builder <distribution, e.g. ubuntu>
You can add other diskimage-builder elements via the
ironic-python-agent-builder -e <extra-element> --release 9-stream centos
You can specify the base name of the target images:
ironic-python-agent-builder -o my-ipa --release 9-stream centos
You can specify the arch of the target image by setting
variable (default is amd64):
ironic-python-agent-builder -o my-ipa --release 9-stream centos
… with diskimage-builder¶
You can also use diskimage-builder directly. First you need to set the
ELEMENTS_PATH variable to the correct location:
If installed with
pip install --user, use:
On Fedora/CentOS/RHEL (installed via
sudo pip installor from packages):
On Debian and its derivatives, if installed with
sudo pip install:
Now you can build an image adding the
disk-image-create -o ironic-python-agent \
To use a specific branch of ironic-python-agent, use:
To build ironic-lib from source, do:
To build image for architectures other than amd64, you can either set the
ARCH environment variable or use
-a to specify the target
disk-image-create -a arm64 -o ironic-python-agent \
Additionally, the IPA ramdisk can be packaged inside of an ISO for use with
some virtual media drivers. Use the
iso-image-create script in
ironic-python-agent-builder repository, passing it the initrd and the
kernel, for example:
./tools/iso-image-create -o /path/to/output.iso -i /path/to/ipa.initrd -k /path/to/ipa.kernel
This is a generic tool that can be used to combine any initrd and kernel into a suitable ISO for booting, and so should work against any IPA ramdisk.
By default rescue mode is enabled in the images. Since it allows to set root password on the ramdisk by anyone on the network, you may disable it if the rescue feature is not supported. Set the following before building the image:
The dynamic-login element allows the operator to inject an SSH key at boot time via the kernel command line parameters:
sshkey="ssh-rsa <your public key here>"to
pxe_append_paramssetting in the
Quotation marks around the public key are important!
Restart the ironic-conductor.
This element is added to the published images by default.
The devuser element allows creating a user at build time, for example:
disk-image-create debian ironic-python-agent-ramdisk devuser
Consistent Network Interface Naming¶
Base cloud images normally disable consistent network interface naming
by inserting an empty udev rule. Include
if you want to have consistent network interface naming whenever it is
required for instance image or deploy image.
ironic-python-agent-builder -e stable-interface-names --release 9-stream centos
By default the element removes some firmware blobs to reduce the image size.
The list can be found below this paragraph. The majority of these firmware
images are used by SoCs, WI-FI chips, some GPUs and Smartnics which are
unlikely to be encountered. If you want to override this, change the
IPA_REMOVE_FIRMWARE environment variable to a comma-separated list
of directories or files under
Set it to an empty string to disable firmware removal.
Ironic Python Agent (IPA) Extra Hardware¶
This element adds the hardware
python package to the Ironic Python Agent (IPA) ramdisk. It also installs
several package dependencies of the
hardware package provides improves hardware introspection capabilities
and supports benchmarking. This functionality may be enabled by adding the
extra-hardware collector in the
[DEFAULT] inspection_collectors option
ipa-inspection-collectors kernel command line argument.
The following environment variables may be set to configure the element when doing a source-based installation:
hardwarePython package descriptor to use. If unset,
DIB_IPA_HARDWARE_VERSIONwill be used.
DIB_IPA_HARDWARE_VERSIONthe version of the
hardwarepackage to install when
DIB_IPA_HARDWARE_PACKAGEis unset. If unset, the latest version will be installed.
Builds a ramdisk with ironic-python-agent.
More information can be found at: https://docs.openstack.org/ironic-python-agent/latest/
Beyond installing the ironic-python-agent, this element does the following:
dhcp-all-interfacesso the node, upon booting, attempts to obtain an IP address on all available network interfaces.
iptablesservice on SysV and systemd based systems.
ufwservice on Upstart based systems.
Installs packages required for the operation of the ironic-python-agent::
When installing from source,
gccare also installed in order to support source based installation of ironic-python-agent and its dependencies.
Install the certificate if any, which is set to the environment variable
DIB_IPA_CERTfor validating the authenticity by ironic-python-agent. The certificate can be self-signed certificate or CA certificate.
Compresses initramfs with command specified in environment variable
DIB_IPA_COMPRESS_CMD, which is ‘gzip’ by default. This command should listen for raw data from stdin and write compressed data to stdout. Command can be with arguments.
Configures rescue mode if
DIB_IPA_ENABLE_RESCUEis not set to
This element outputs two files:
$IMAGE-NAME.initramfs: The deploy ramdisk file containing the ironic-python-agent (IPA) service.
$IMAGE-NAME.kernel: The kernel binary file.
The package based install currently only enables the service when using the systemd init system. This can easily be changed if there is an agent package which includes upstart or sysv packaging.
Using the ramdisk will require at least 1.5GB of ram
Adds TLS support to ironic-python-agent-ramdisk.
By default this element will enable TLS API support in IPA with a self-signed certificate and key created at build time.
Optionally, you can provide your own SSL certificate and key, and optionally CA, via the following environment variables. They should be set to an accessible path on the build systems filesystem. If set, they will be copied into the built ramdisk, and IPA will be configured to use them.
The environment variables are:
DIB_IPA_CERT_FILEshould point to the TLS certificate for ramdisk use.
DIB_IPA_KEY_FILEshould point to the private key matching
You can configure the generated certificate with the following environment variables:
DIB_IPA_CERT_HOSTNAMEthe CN for the generated certificate. Defaults to “ipa-ramdisk.example.com”.
DIB_IPA_CERT_EXPIRATIONexpiration, in days, for the certificate. Defaults to 1095 (three years).
Note that the certificates generated by this element are self-signed, and any nodes using them will need to set agent_verify_ca=False in driver_info.
This element can also configure client certificate validation in IPA. If you
wish to validate client certificates, set
DIB_IPA_CA_FILE to a CA file
you wish IPA client connections to be validated against. This CA file will
be copied into the built ramdisk, and IPA will be configured to use it.