kayobe/doc/source/configuration/reference/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 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 documentation <> for full details.

The default configuration builds a CentOS Stream 9 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_host_packages_extra

List of additional build host packages to install. Default is an empty list.

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"] when os_distribution is "rocky", and ["ubuntu", "enable-serial-console", "ironic-python-agent-ramdisk"] otherwise.

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": "9-stream", "DIB_REPOLOCATION_ironic_python_agent": "{{ ipa_build_source_url }}", "DIB_REPOREF_ironic_python_agent": "{{ ipa_build_source_version }}", "DIB_REPOREF_requirements": "{{ openstack_branch }}"} if os_distribution is "rocky" else {"DIB_RELEASE": "jammy", "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.openstack.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.openstack.os_images role for usage. Default is none.

ipa_build_dib_git_elements

List of git repositories containing Diskimage Builder (DIB) elements. See stackhpc.openstack.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:

ipa_build_images: true

Example: Installing IPA from a custom git repository

To install IPA from a custom git repository:

ipa_source_url: https://git.example.com/ironic-python-agent
ipa_source_version: downstream

Example: Adding an element

In the following example, we extend the list of DIB elements to add the mellanox element <elements/mellanox/README>, which can be useful for inspecting hardware with Mellanox InfiniBand NICs.

ipa_build_dib_elements_extra:
  - "mellanox"

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

ipa_build_dib_elements_extra:
  - "devuser"

ipa_build_dib_env_extra:
  DIB_DEV_USER_USERNAME: "devuser"
  DIB_DEV_USER_PASSWORD: "correct horse battery staple"
  DIB_DEV_USER_PWDLESS_SUDO: "yes"

Alternatively, the 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 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.

ipa_build_dib_elements_extra:
  - "my-element"

ipa_build_dib_git_elements:
  - repo: "https://git.example.com/custom-dib-elements"
    local: "{{ source_checkout_path }}/custom-dib-elements"
    version: "master"
    elements_path: "elements"

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:

ipa_build_dib_packages:
  - "biosdevname"

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 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-centos9{{ 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-centos9{{ 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:

ipa_collectors_extra:
  - "extra-hardware"

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:

ipa_build_dib_elements_extra:
  - "extra-hardware"

Example: Passing additional kernel arguments to IPA

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

ipa_kernel_options_extra:
  - "foo=bar"