Newer
Older
=========================
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 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
<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
}}``.
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
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_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``.
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
``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:
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"