diff --git a/doc/source/install/index.rst b/doc/source/install/index.rst index 2d84d6729..15f6a860c 100644 --- a/doc/source/install/index.rst +++ b/doc/source/install/index.rst @@ -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 ================= diff --git a/doc/source/user/architecture.rst b/doc/source/user/architecture.rst new file mode 100644 index 000000000..72df3e568 --- /dev/null +++ b/doc/source/user/architecture.rst @@ -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/`` + is a source directory for project ```` (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 ``--[cleaning-].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/ diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst index da95fcff0..70b8f2bfc 100644 --- a/doc/source/user/index.rst +++ b/doc/source/user/index.rst @@ -8,6 +8,7 @@ this documentation serves as a blend of both Admin and User documentation. .. toctree:: :maxdepth: 1 + architecture howto troubleshooting keystone