openstack/bifrost
Code Issues Proposed changes

Merge "Start Bifrost Architecture documentation"

Browse Source
This commit is contained in:
Zuul 2022-01-25 12:27:36 +00:00 committed by Gerrit Code Review
commit a4657cc600
3 changed files with 187 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
doc/source/install/index.rst
View File

@ -61,6 +61,9 @@ Installation of Bifrost can be done in three ways:
* By writing your own playbooks using Ansible roles provided with Bifrost.
If you want to understand what and how is installed by Bifrost, please see
:doc:`/user/architecture`.
=================
Pre-install steps
=================

183
doc/source/user/architecture.rst Normal file
View File

@ -0,0 +1,183 @@
Bifrost Architecture
====================
This document describes what and how Bifrost installs in the default set up
(e.g. one created by ``./bifrost-cli install``).
Components
----------
Bifrost installs the following main components:
ironic_
Ironic is the main service that provides bare metal capabilities.
Its `bare metal API`_ is served on TCP port 6385.
ironic-inspector_
Inspector is an auxiliary service that provides `in-band inspection`_.
Its `introspection API`_ is served on TCP port 5050.
Inspector can be disabled by setting ``enable_inspector=false``.
mariadb_
MariaDB is used as a database to persistently store information.
nginx_
Nginx is used as a web server for three main purposes:
* to serve iPXE configuration scripts when booting nodes over network,
* to serve virtual media ISO images to BMC when booting nodes over virtual
CD,
* to serve instance images to the ramdisk when deploying nodes.
Uses HTTP port 8080 by default (can be changed via the ``file_url_port``
parameter).
dnsmasq_
Dnsmasq is used as a DHCP and TFTP server (but not for DNS by default)
when booting nodes over network. It can also be used to provide DHCP
to deployed nodes.
Dnsmasq can be disabled by setting ``include_dhcp_server=false``
or passing ``--disable-dhcp`` to ``bifrost-cli``.
The following components can be enabled if needed:
keystone_
Keystone is an OpenStack Identity service. It can be used to provide
sophisticated authentication to Ironic and Inspector instead of HTTP basic
authentication. Its `identity API`_ is served using uWSGI and Nginx on the
port 5000.
See :doc:`/user/keystone` for details.
ironic-prometheus-exporter_
An exporter that exposes hardware metrics from the node's BMC (using IPMI
or Redfish) for consumptions by Prometheus_.
The exporter can be enabled by setting ``enable_prometheus_exporter=true``
or passing ``--enable-prometheus-exporter`` to ``bifrost-cli``.
Networking
----------
:doc:`/install/index` requires to specify the network interface which will be
used for communication with the nodes. On systems that use firewalld_, a new
zone ``bifrost`` is created with this interface, and firewall settings are
adjusted to allow boot traffic (DHCP, TFTP, etc) through this interface.
Virtual testing environments use network interface ``virbr0``, IP subnet
``192.168.122.1/24`` and the ``libvirt`` firewalld zone by default.
Parameters
~~~~~~~~~~
``network_interface``
the main network interface for provisioning nodes. It is recommended to use
an isolated network for this purpose.
``internal_ip``
IPv4 address of the Bifrost node on the provisioning interface. Normally
derived automatically. You can use the following command to detect it:
.. code-block:: console
$ sudo awk '/^tftp_server =/ { print $3 }' /etc/ironic/ironic.conf
192.168.122.1
This IP address is used for all provisioning traffic: TFTP, iPXE,
call-backs to Ironic and Inspector. It is also used for the traffic between
the services.
``public_ip``
IPv4 address of the Bifrost node that is accessible outside of the
provisioning environment. Used e.g. to provide public URLs for the service
catalog, when Keystone support is enabled.
.. note::
Bifrost does not currently support IPv6, contributions are welcome.
Locations
---------
Installation locations
~~~~~~~~~~~~~~~~~~~~~~
``/opt/stack/bifrost``
is a Python virtual environment where all Python packages are installed.
``/opt/stack/<reponame>``
is a source directory for project ``<reponame>`` (e.g. ``ironic``)
installed from source. Services are installed this way, while libraries are
mostly installed as packages.
Log locations
~~~~~~~~~~~~~
journald
is used for logging from most services. For example, to get Inspector logs:
.. code-block:: console
$ sudo journalctl -u ironic-inspector
``/var/log/ironic/deploy``
contains tarballs with ramdisk logs from deployment or cleaning. The file
name format is ``<node UUID>-<node name>-[cleaning-]<datatime>.tar.gz``.
You can access the main logs like this:
.. code-block:: console
$ cd $(mktemp -d)
$ sudo tar -xzf \
/var/log/ironic/deploy/493aacf2-90ec-5e3d-9ce5-ea496f12e2a5_testvm3_2021-11-08-17-34-18.tar.gz
$ less journal # for ramdisks that use systemd, e.g. DIB-built
$ less var/log/ironic-python-agent.log # for tinyIPA and similar
``/var/log/ironic-inspector/ramdisk``
contains tarballs with ramdisk logs from inspection. They are very similar
to ramdisk logs from deployment and cleaning.
Runtime locations
~~~~~~~~~~~~~~~~~
``/var/lib/ironic/httpboot``
HTTP root directory. Contains iPXE scripts and images, including
``deployment_image.qcow2`` which is built or downloaded during Bifrost
installation.
You can detect the root URL with the following command:
.. code-block:: console
$ sudo awk '/^http_url =/ { print $3 }' /etc/ironic/ironic.conf
http://192.168.122.1:8080/
``/var/lib/tftpboot``
TFTP root directory. Normally contains only the binaries to run iPXE on
systems that don't have an iPXE firmware built in. Can contain images when
the ``pxe`` boot interface is used.
``/var/lib/ironic/master_images``
cache for instance images.
``/var/lib/ironic/master_iso_images``
cache for virtual media ISO images.
``/var/lib/ironic/certificates``
TLS certificates that are used to communicate to the ramdisk on the nodes
when cleaning or deploying.
.. _ironic: https://docs.openstack.org/ironic/latest/
.. _bare metal API: https://docs.openstack.org/api-ref/baremetal/
.. _ironic-inspector: https://docs.openstack.org/ironic-inspector/latest/
.. _in-band inspection: https://docs.openstack.org/ironic/latest/admin/inspection.html#in-band-inspection
.. _introspection API: https://docs.openstack.org/api-ref/baremetal-introspection/
.. _mariadb: https://mariadb.org/
.. _nginx: https://nginx.org/
.. _dnsmasq: https://dnsmasq.org/
.. _keystone: https://docs.openstack.org/keystone/latest/
.. _identity API: https://docs.openstack.org/api-ref/identity/v3/index.html
.. _ironic-prometheus-exporter: https://docs.openstack.org/ironic-prometheus-exporter/latest/
.. _prometheus: https://prometheus.io/
.. _firewalld: https://firewalld.org/

1
doc/source/user/index.rst
View File

@ -8,6 +8,7 @@ this documentation serves as a blend of both Admin and User documentation.
.. toctree::
:maxdepth: 1
architecture
howto
troubleshooting
keystone