=========================
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.

.. _configuration-ipa-build:

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 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"]``.
``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 }}"}``.
``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
    <https://galaxy.ansible.com/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
    <https://galaxy.ansible.com/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 <https://galaxy.ansible.com/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:

.. code-block:: yaml
   :caption: ``ipa.yml``

   ipa_build_images: true

Example: Installing IPA from a custom git repository
----------------------------------------------------

To install IPA from a custom git repository:

.. code-block:: yaml
   :caption: ``ipa.yml``

   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
:diskimage-builder-doc:`mellanox element <elements/mellanox/README>`, which can
be useful for inspecting hardware with Mellanox InfiniBand NICs.

.. code-block:: yaml
   :caption: ``ipa.yml``

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

.. code-block:: yaml
   :caption: ``ipa.yml``

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

.. code-block:: yaml
   :caption: ``ipa.yml``

   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:

.. code-block:: yaml
   :caption: ``ipa.yml``

   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-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-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
<https://pypi.org/project/hardware/>`__, which is not installed in IPA images
by default.

The following example enables the ``extra-hardware`` collector:

.. code-block:: yaml
   :caption: ``ipa.yml``

   ipa_collectors_extra:
     - "extra-hardware"

The ``ironic-python-agent-builder`` repository provides an `extra-hardware
element
<https://docs.openstack.org/ironic-python-agent-builder/latest/admin/dib.html#ironic-python-agent-ipa-extra-hardware>`__
which may be used to install this package. It may be used as follows if
building an IPA image locally:

.. code-block:: yaml
   :caption: ``ipa.yml``

   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:

.. code-block:: yaml
   :caption: ``ipa.yml``

   ipa_kernel_options_extra:
     - "foo=bar"
