Browse Source

Merge "Add documentation about the available Elements"

Zuul 3 months ago
committed by Gerrit Code Review
1 changed files with 99 additions and 0 deletions
  1. +99

+ 99
- 0
doc/source/admin/dib.rst View File

@ -158,3 +158,102 @@ required for instance image or deploy image.
.. _diskimage-builder:
.. _dynamic-login:
.. _devuser:
Available Elements
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`` module.
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
or the ``ipa-inspection-collectors`` kernel command line argument.
The following environment variables may be set to configure the element when
doing a source-based installation:
* ``DIB_IPA_HARDWARE_PACKAGE`` the full ``hardware`` Python package descriptor
to use. If unset, ``DIB_IPA_HARDWARE_VERSION`` will be used.
* ``DIB_IPA_HARDWARE_VERSION`` the version of the ``hardware`` package to
install when ``DIB_IPA_HARDWARE_PACKAGE`` is unset. If unset, the latest
version will be installed.
Builds a ramdisk with ironic-python-agent.
More information can be found at:
Beyond installing the ironic-python-agent, this element does the following:
* Installs the ``dhcp-all-interfaces`` so the node, upon booting, attempts to
obtain an IP address on all available network interfaces.
* Disables the ``iptables`` service on SysV and systemd based systems.
* Disables the ``ufw`` service on Upstart based systems.
* Installs packages required for the operation of the ironic-python-agent::
``qemu-utils`` ``parted`` ``hdparm`` ``util-linux`` ``genisoimage``
* When installing from source, ``python-dev`` and ``gcc`` are also installed
in order to support source based installation of ironic-python-agent and its
* Install the certificate if any, which is set to the environment variable
``DIB_IPA_CERT`` for 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_RESCUE`` is not set to ``false``.
This element outputs three files:
- ``$IMAGE-NAME.initramfs``: The deploy ramdisk file containing the
ironic-python-agent (IPA) service.
- ``$IMAGE-NAME.kernel``: The kernel binary file.
.. note::
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.
.. note::
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 certifiate 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_FILE`` should point to the TLS certificate for ramdisk use.
- ``DIB_IPA_KEY_FILE`` should point to the private key matching
You can configure the generated certificate with the following environment variables:
- ``DIB_IPA_CERT_HOSTNAME`` the CN for the generated
certificate. Defaults to "".
- ``DIB_IPA_CERT_EXPIRATION`` expiration, 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.