ironic-python-agent.rst



Ironic Python Agent (IPA)
This section covers configuration of Ironic Python Agent (IPA) which is used by
Ironic and Ironic Inspector to deploy and inspect bare metal nodes. This is
used by the Bifrost services that run on the seed host, and also by Ironic and
Ironic Inspector services running in the overcloud for bare metal compute, if
enabled (kolla_enable_ironic is true). IPA configuration is typically
applied in ${KAYOBE_CONFIG_PATH}/ipa.yml. Consult the
:ironic-python-agent-doc:`IPA documentation <>` for full details of IPA usage
and configuration.

Ironic Python Agent (IPA) image build configuration

Note
This section may be skipped if not building IPA images locally
(ipa_build_images is false).

The following options cover building of IPA images via Diskimage-builder (DIB).
Consult the :diskimage-builder-doc:`Diskimage-builder documentation <>` for
full details.
The default configuration builds a CentOS 8 ramdisk image which includes the
upstream IPA source code, and has a serial console enabled.
The images are built for Bifrost via kayobe seed deployment image build,
and for Ironic in the overcloud (if enabled) via kayobe overcloud deployment
image build.

ipa_build_images
Whether to build IPA images from source. Default is False.
ipa_build_source_url
URL of IPA source repository. Default is
https://opendev.org/openstack/ironic-python-agent

ipa_build_source_version
Version of IPA source repository. Default is {{ openstack_branch }}.
ipa_builder_source_url
URL of IPA builder source repository. Default is
https://opendev.org/openstack/ironic-python-agent-builder

ipa_builder_source_version
Version of IPA builder source repository. Default is master.
ipa_build_dib_elements_default
List of default Diskimage Builder (DIB) elements to use when building IPA
images. Default is ["centos", "enable-serial-console",
"ironic-python-agent-ramdisk"].
ipa_build_dib_elements_extra
List of additional Diskimage Builder (DIB) elements to use when building IPA
images. Default is empty.
ipa_build_dib_elements
List of Diskimage Builder (DIB) elements to use when building IPA images.
Default is combination of ipa_build_dib_elements_default and
ipa_build_dib_elements_extra.
ipa_build_dib_env_default
Dictionary of default environment variables to provide to Diskimage Builder
(DIB) during IPA image build. Default is
{"DIB_RELEASE": "8-stream", "DIB_REPOLOCATION_ironic_python_agent": "{{
ipa_build_source_url }}", "DIB_REPOREF_ironic_python_agent": "{{
ipa_build_source_version }}", "DIB_REPOREF_requirements": "{{
openstack_branch }}"}.
ipa_build_dib_env_extra
Dictionary of additional environment variables to provide to Diskimage
Builder (DIB) during IPA image build. Default is empty.
ipa_build_dib_env
Dictionary of environment variables to provide to Diskimage Builder (DIB)
during IPA image build. Default is a combination of
ipa_build_dib_env_default and ipa_build_dib_env_extra.
ipa_build_dib_git_elements_default
List of default git repositories containing Diskimage Builder (DIB)
elements. See stackhpc.os-images role for usage. Default
is one item for IPA builder.
ipa_build_dib_git_elements_extra
List of additional git repositories containing Diskimage Builder (DIB)
elements. See stackhpc.os-images role for usage. Default
is none.
ipa_build_dib_git_elements
List of git repositories containing Diskimage Builder (DIB) elements. See
stackhpc.os-images role
for usage. Default is combination of ipa_build_dib_git_elements_default
and ipa_build_dib_git_elements_extra.
ipa_build_dib_packages
List of DIB packages to install. Default is none.
ipa_build_upper_constraints_file
Upper constraints file for installing packages in the virtual environment
used for building IPA images. Default is {{ pip_upper_constraints_file
}}.


Example: Building IPA images locally
To build IPA images locally:

Example: Installing IPA from a custom git repository
To install IPA from a custom git repository:

Example: Adding an element
In the following example, we extend the list of DIB elements to add the
:diskimage-builder-doc:`mellanox element <elements/mellanox/README>`, which can
be useful for inspecting hardware with Mellanox InfiniBand NICs.

Example: Configuring a development user account

Warning
A development user account should not be used in production.

When debugging a failed deployment, it can sometimes be necessary to allow
access to the image via a preconfigured user account with a known password.
This can be achieved via the :diskimage-builder-doc:`devuser
<elements/devuser/README>` element.
This example shows how to add the devuser element, and configure a username
and password for an account that has passwordless sudo:
Alternatively, the :diskimage-builder-doc:`dynamic-login element
<elements/dynamic-login/README>` can be used to authorize SSH keys by appending
them to the kernel arguments.
Further information on troubleshooting IPA can be found
:ironic-python-agent-doc:`here <admin/troubleshooting>`.

Example: Configuring custom DIB elements
Sometimes it is useful to use custom DIB elements that are not shipped with DIB
itself. This can be done by sharing them in a git repository.
In this example the master branch of
https://git.example.com/custom-dib-elements would have a top level elements
directory, containing a my-element directory for the element.

Example: Installing a package
It can be necessary to install additional packages in the IPA image. Rather
than needing to write a custom DIB element, we can use the
ipa_build_dib_packages variable. For example, to install the
biosdevname package:

Ironic Python Agent (IPA) images configuration

Note
If building IPA images locally (ipa_build_images is true) this
section can be skipped.

The following options configure the source of Ironic Python Agent images for
inspection and deployment.  Consult the :ironic-python-agent-doc:`Ironic Python
Agent documentation <>` for full details.

ipa_images_upstream_url_suffix
Suffix of upstream Ironic deployment image files. Default is based on
{{ openstack_branch }}.
ipa_images_kernel_name
Name of Ironic deployment kernel image to register in Glance. Default is
ipa.kernel.
ipa_kernel_upstream_url
URL of Ironic deployment kernel image to download. Default is
https://tarballs.openstack.org/ironic-python-agent/dib/files/ipa-centos8{{
ipa_images_upstream_url_suffix }}.kernel.
ipa_kernel_checksum_url
URL of checksum of Ironic deployment kernel image. Default is {{
ipa_kernel_upstream_url }}.{{ ipa_kernel_checksum_algorithm }}.
ipa_kernel_checksum_algorithm
Algorithm of checksum of Ironic deployment kernel image. Default is
sha256.
ipa_images_ramdisk_name
Name of Ironic deployment ramdisk image to register in Glance. Default is
ipa.initramfs.
ipa_ramdisk_upstream_url
URL of Ironic deployment ramdisk image to download. Default is
https://tarballs.openstack.org/ironic-python-agent/dib/files/ipa-centos8{{
ipa_images_upstream_url_suffix }}.initramfs.
ipa_ramdisk_checksum_url
URL of checksum of Ironic deployment ramdisk image. Default is {{
ipa_ramdisk_upstream_url }}.{{ ipa_ramdisk_checksum_algorithm }}.
ipa_ramdisk_checksum_algorithm
Algorithm of checksum of Ironic deployment ramdisk image. Default is
sha256.


Ironic Python Agent (IPA) deployment configuration
The following options configure how IPA operates during deployment and
inspection.

ipa_collect_lldp
Whether to enable collection of LLDP TLVs. Default is True.
ipa_collectors_default


Note
extra-hardware is not currently included as it requires a ramdisk
with the hardware python module installed.

List of default inspection collectors to run. Default is ["default",
"logs", "pci-devices"].

ipa_collectors_extra
List of additional inspection collectors to run. Default is none.
ipa_collectors
List of inspection collectors to run. Default is a combination of
ipa_collectors_default and ipa_collectors_extra.
ipa_benchmarks_default
List of default inspection benchmarks to run. Default is ["cpu", "disk",
"ram"].
ipa_benchmarks_extra
List of extra inspection benchmarks to run. Default is none.
ipa_benchmarks


Note
The extra-hardware collector must be enabled in order to execute
benchmarks during inspection.

List of inspection benchmarks to run. Default is a combination of
ipa_benchmarks_default and ipa_benchmarks_extra.

ipa_kernel_options_default
List of default kernel parameters for Ironic python agent. Default includes
ipa-collect-lldp, ipa-inspection-collectors and
ipa-inspection-benchmarks, with arguments taken from
ipa_collect_lldp, ipa_collectors and ipa_benchmarks.
ipa_kernel_options_extra
List of additional kernel parameters for Ironic python agent. Default is
none.
ipa_kernel_options
List of kernel parameters for Ironic python agent. Default is a combination
of ipa_kernel_options_default and ipa_kernel_options_extra.


Example: Adding the extra-hardware collector
The extra-hardware collector may be used to collect additional information
about hardware during inspection. It is also a requirement for running
benchmarks. This collector depends on the Python hardware package, which is not installed in IPA images
by default.
The following example enables the extra-hardware collector:
The ironic-python-agent-builder repository provides an extra-hardware
element
which may be used to install this package. It may be used as follows if
building an IPA image locally:

Example: Passing additional kernel arguments to IPA
The following example shows how to pass additional kernel arguments to IPA: