Install and configure the Bare Metal service¶
This section describes how to install and configure the Bare Metal service, code-named ironic, manually from packages on one of the three popular families of Linux distributions.
Alternatively, you can use one of the numerous projects that install ironic. One of them is provided by the bare metal team:
Bifrost installs ironic in the standalone mode (without the rest of OpenStack).
More installation projects are developed by other OpenStack teams:
Kolla can install ironic in containers as part of OpenStack.
OpenStack-Ansible has a role to install ironic.
TripleO uses ironic for provisioning bare metal nodes and can also be used to install ironic.
Install and configure prerequisites¶
The Bare Metal service is a collection of components that provides support to manage and provision physical machines. You can configure these components to run on separate nodes or the same node. In this guide, the components run on one node, typically the Compute Service’s compute node.
It assumes that the Identity, Image, Compute, and Networking services have already been set up.
Set up the database for Bare Metal¶
The Bare Metal service stores information in a database. This guide uses the MySQL database that is used by other OpenStack services.
In MySQL, create an ironic
database that is accessible by the
ironic
user. Replace IRONIC_DBPASSWORD
with a suitable password:
# mysql -u root -p
mysql> CREATE DATABASE ironic CHARACTER SET utf8mb3;
mysql> GRANT ALL PRIVILEGES ON ironic.* TO 'ironic'@'localhost' \
IDENTIFIED BY 'IRONIC_DBPASSWORD';
mysql> GRANT ALL PRIVILEGES ON ironic.* TO 'ironic'@'%' \
IDENTIFIED BY 'IRONIC_DBPASSWORD';
Note
When creating the database to house Ironic, specifically on MySQL/MariaDB,
the character set cannot be 4 byte Unicode characters. This is due to
an internal structural constraint. UTF8, in these database platforms,
has traditionally meant utf8mb3
, short for “UTF-8, 3 byte encoding”,
however the platforms are expected to move to utf8mb4
which is
incompatible with Ironic.
Running on SQLite¶
It is possible to run the Bare Metal service with SQLite as the database backend. However, take into account the following limitations:
You have to run Ironic in the all-in-one mode (see configuring single-process ironic). You cannot have multiple conductors this way.
You should use WAL mode for the database. Ironic will try to enable it for you, but it can only be done for a fresh database.
Even in the WAL mode, SQLite has limited write concurrency. If you experience “database is locked” errors, try reducing the frequency of periodic tasks. If that still does not help, you may need to use a server-based database.
Not all database migrations are supported on SQLite. You may need to re-create the database on upgrades.
To use SQLite, configure your connection like this:
[database]
connection = sqlite:////full/path/to/ironic.sqlite
Note
This is not a typo! A full path requires 4 slashes.
If in doubt, use MySQL/MariaDB instead.
Install and configure components¶
Using DNF on RHEL/CentOS Stream and RDO packages:
# dnf install openstack-ironic-api openstack-ironic-conductor python3-ironicclient
On Ubuntu/Debian:
# apt-get install ironic-api ironic-conductor python3-ironicclient
On openSUSE/SLES:
# zypper install openstack-ironic-api openstack-ironic-conductor python3-ironicclient
Warning
Support for SUSE systems is best effort, it is not tested in the CI.
The Bare Metal service is configured via its configuration file. This file
is typically located at /etc/ironic/ironic.conf
.
Although some configuration options are mentioned here, it is recommended that you review all the Sample Configuration File so that the Bare Metal service is configured for your needs.
It is possible to set up an ironic-api and an ironic-conductor services on the same host or different hosts. Users also can add new ironic-conductor hosts to deal with an increasing number of bare metal nodes. But the additional ironic-conductor services should be at the same version as that of existing ironic-conductor services.
Configuring ironic-api service¶
The Bare Metal service stores information in a database. This guide uses the MySQL database that is used by other OpenStack services.
Configure the location of the database via the
connection
option. In the following, replaceIRONIC_DBPASSWORD
with the password of yourironic
user, and replaceDB_IP
with the IP address where the DB server is located:[database] # The SQLAlchemy connection string used to connect to the # database (string value) connection=mysql+pymysql://ironic:IRONIC_DBPASSWORD@DB_IP/ironic?charset=utf8
Configure the ironic-api service to use the RabbitMQ message broker by setting the following option. Replace
RPC_*
with appropriate address details and credentials of RabbitMQ server:[DEFAULT] # A URL representing the messaging driver to use and its full # configuration. (string value) transport_url = rabbit://RPC_USER:RPC_PASSWORD@RPC_HOST:RPC_PORT/
Alternatively, you can use JSON RPC for interactions between ironic-conductor and ironic-api. Enable it in the configuration and provide the keystone credentials to use for authentication:
[DEFAULT] rpc_transport = json-rpc [json_rpc] # Authentication type to load (string value) auth_type = password # Authentication URL (string value) auth_url=https://IDENTITY_IP:5000/ # Username (string value) username=ironic # User's password (string value) password=IRONIC_PASSWORD # Project name to scope to (string value) project_name=service # Domain ID containing project (string value) project_domain_id=default # User's domain id (string value) user_domain_id=default
If you use port other than the default 8089 for JSON RPC, you have to configure it, for example:
[json_rpc] port = 9999
Configure the ironic-api service to use these credentials with the Identity service. Replace
PUBLIC_IDENTITY_IP
with the public IP of the Identity server,PRIVATE_IDENTITY_IP
with the private IP of the Identity server and replaceIRONIC_PASSWORD
with the password you chose for theironic
user in the Identity service:[DEFAULT] # Authentication strategy used by ironic-api: one of # "keystone" or "noauth". "noauth" should not be used in a # production environment because all authentication will be # disabled. (string value) auth_strategy=keystone [keystone_authtoken] # Authentication type to load (string value) auth_type=password # Complete public Identity API endpoint (string value) www_authenticate_uri=http://PUBLIC_IDENTITY_IP:5000 # Complete admin Identity API endpoint. (string value) auth_url=http://PRIVATE_IDENTITY_IP:5000 # Service username. (string value) username=ironic # Service account password. (string value) password=IRONIC_PASSWORD # Service tenant name. (string value) project_name=service # Domain name containing project (string value) project_domain_name=Default # User's domain name (string value) user_domain_name=Default
Create the Bare Metal service database tables:
$ ironic-dbsync --config-file /etc/ironic/ironic.conf create_schema
Restart the ironic-api service:
RHEL/CentOS/SUSE:
sudo systemctl restart openstack-ironic-api
Ubuntu/Debian:
sudo service ironic-api restart
Configuring ironic-api behind mod_wsgi¶
Bare Metal service comes with an example file for configuring the
ironic-api
service to run behind Apache with mod_wsgi.
Note
This is optional, the ironic APIs can be run using independent scripts that provide HTTP servers. But it is generally considered more performant and flexible to run them using a generic HTTP server that supports WSGI (such as Apache or nginx).
Install the apache service:
Fedora/RHEL8/CentOS8:
sudo dnf install httpd
Debian/Ubuntu:
apt-get install apache2
SUSE:
zypper install apache2
Download the
etc/apache2/ironic
file from the Ironic project tree and copy it to the apache sites:Fedora/RHEL8/CentOS8:
sudo cp etc/apache2/ironic /etc/httpd/conf.d/ironic.conf
Debian/Ubuntu:
sudo cp etc/apache2/ironic /etc/apache2/sites-available/ironic.conf
SUSE:
sudo cp etc/apache2/ironic /etc/apache2/vhosts.d/ironic.conf
Edit the recently copied
<apache-configuration-dir>/ironic.conf
:Modify the
WSGIDaemonProcess
,APACHE_RUN_USER
andAPACHE_RUN_GROUP
directives to set the user and group values to an appropriate user on your server.Modify the
WSGIScriptAlias
directive to point to the automatically generatedironic-api-wsgi
script that is located in IRONIC_BIN directory.Modify the
Directory
directive to set the path to the Ironic API code.Modify the
ErrorLog
andCustomLog
to redirect the logs to the right directory (on Red Hat systems this is usually under /var/log/httpd).
Stop and disable the ironic-api service. If ironic-api service is started, the port will be occupied. Apach will fail to start:
Fedora/RHEL8/CentOS8/SUSE:
sudo systemctl stop openstack-ironic-api sudo systemctl disable openstack-ironic-api
Debian/Ubuntu:
sudo service ironic-api stop sudo service ironic-api disable
Enable the apache
ironic
in site and reload:Fedora/RHEL8/CentOS8:
sudo systemctl reload httpd
Debian/Ubuntu:
sudo a2ensite ironic sudo service apache2 reload
SUSE:
sudo systemctl reload apache2
Note
The file ironic-api-wsgi
is automatically generated by pbr and is
available in IRONIC_BIN directory. It should not be modified.
Configure another WSGI container¶
A slightly different approach has to be used for WSGI containers that cannot
use ironic-api-wsgi
. For example, for gunicorn:
gunicorn -b 0.0.0.0:6385 'ironic.api.wsgi:initialize_wsgi_app(argv=[])'
If you want to pass a configuration file, use:
gunicorn -b 0.0.0.0:6385 \
'ironic.api.wsgi:initialize_wsgi_app(argv=["ironic-api", "--config-file=/path/to/_ironic.conf"])'
Configuring ironic-conductor service¶
Replace
HOST_IP
with IP of the conductor host.[DEFAULT] # IP address of this host. If unset, will determine the IP # programmatically. If unable to do so, will use "127.0.0.1". # (string value) my_ip=HOST_IP
Note
If a conductor host has multiple IPs,
my_ip
should be set to the IP which is on the same network as the bare metal nodes.Configure the location of the database. Ironic-conductor should use the same configuration as ironic-api. Replace
IRONIC_DBPASSWORD
with the password of yourironic
user, and replace DB_IP with the IP address where the DB server is located:[database] # The SQLAlchemy connection string to use to connect to the # database. (string value) connection=mysql+pymysql://ironic:IRONIC_DBPASSWORD@DB_IP/ironic?charset=utf8
Configure the ironic-conductor service to use the RabbitMQ message broker by setting the following option. Ironic-conductor should use the same configuration as ironic-api. Replace
RPC_*
with appropriate address details and credentials of RabbitMQ server:[DEFAULT] # A URL representing the messaging driver to use and its full # configuration. (string value) transport_url = rabbit://RPC_USER:RPC_PASSWORD@RPC_HOST:RPC_PORT/
Alternatively, you can use JSON RPC for interactions between ironic-conductor and ironic-api. Enable it in the configuration and provide the keystone credentials to use for authenticating incoming requests (can be the same as for the API):
[DEFAULT] rpc_transport = json-rpc [keystone_authtoken] # Authentication type to load (string value) auth_type=password # Complete public Identity API endpoint (string value) www_authenticate_uri=http://PUBLIC_IDENTITY_IP:5000 # Complete admin Identity API endpoint. (string value) auth_url=http://PRIVATE_IDENTITY_IP:5000 # Service username. (string value) username=ironic # Service account password. (string value) password=IRONIC_PASSWORD # Service tenant name. (string value) project_name=service # Domain name containing project (string value) project_domain_name=Default # User's domain name (string value) user_domain_name=Default
You can optionally change the host and the port the JSON RPC service will bind to, for example:
[json_rpc] host_ip = 192.168.0.10 port = 9999
Warning
Hostnames of ironic-conductor machines must be resolvable by ironic-api services when JSON RPC is used.
Configure credentials for accessing other OpenStack services.
In order to communicate with other OpenStack services, the Bare Metal service needs to use service users to authenticate to the OpenStack Identity service when making requests to other services. These users’ credentials have to be configured in each configuration file section related to the corresponding service:
[neutron]
- to access the OpenStack Networking service[glance]
- to access the OpenStack Image service[swift]
- to access the OpenStack Object Storage service[cinder]
- to access the OpenStack Block Storage service[inspector]
- to access the OpenStack Bare Metal Introspection service[service_catalog]
- a special section holding credentials the Bare Metal service will use to discover its own API URL endpoint as registered in the OpenStack Identity service catalog.
For simplicity, you can use the same service user for all services. For backward compatibility, this should be the same user configured in the
[keystone_authtoken]
section for the ironic-api service (see “Configuring ironic-api service”). However, this is not necessary, and you can create and configure separate service users for each service.Under the hood, Bare Metal service uses
keystoneauth
library together withAuthentication plugin
,Session
andAdapter
concepts provided by it to instantiate service clients. Please refer to Keystoneauth documentation for supported plugins, their available options as well as Session- and Adapter-related options for authentication, connection and endpoint discovery respectively.In the example below, authentication information for user to access the OpenStack Networking service is configured to use:
Networking service is deployed in the Identity service region named
RegionTwo
, with only itspublic
endpoint interface registered in the service catalog.HTTPS connection with specific CA SSL certificate when making requests
the same service user as configured for ironic-api service
dynamic
password
authentication plugin that will discover appropriate version of Identity service API based on other provided optionsreplace
IDENTITY_IP
with the IP of the Identity server, and replaceIRONIC_PASSWORD
with the password you chose for theironic
user in the Identity service
[neutron] # Authentication type to load (string value) auth_type = password # Authentication URL (string value) auth_url=https://IDENTITY_IP:5000/ # Username (string value) username=ironic # User's password (string value) password=IRONIC_PASSWORD # Project name to scope to (string value) project_name=service # Domain ID containing project (string value) project_domain_id=default # User's domain id (string value) user_domain_id=default # PEM encoded Certificate Authority to use when verifying # HTTPs connections. (string value) cafile=/opt/stack/data/ca-bundle.pem # The default region_name for endpoint URL discovery. (string # value) region_name = RegionTwo # List of interfaces, in order of preference, for endpoint # URL. (list value) valid_interfaces=public
By default, in order to communicate with another service, the Bare Metal service will attempt to discover an appropriate endpoint for that service via the Identity service’s service catalog. The relevant configuration options from that service group in the Bare Metal service configuration file are used for this purpose. If you want to use a different endpoint for a particular service, specify this via the
endpoint_override
configuration option of that service group, in the Bare Metal service’s configuration file. Taking the previous Networking service example, this would be[neutron] ... endpoint_override = <NEUTRON_API_ADDRESS>
(Replace <NEUTRON_API_ADDRESS> with actual address of a specific Networking service endpoint.)
Configure enabled drivers and hardware types as described in Enabling drivers and hardware types.
If you enabled any driver that uses Direct deploy, Swift backend for the Image service must be installed and configured, see Configure the Image service for temporary URLs. Ceph Object Gateway (RADOS Gateway) is also supported as the Image service’s backend, see Ceph Object Gateway support.
Configure the network for ironic-conductor service to perform node cleaning, see Node cleaning from the admin guide.
Restart the ironic-conductor service:
RHEL/CentOS/SUSE:
sudo systemctl restart openstack-ironic-conductor
Ubuntu/Debian:
sudo service ironic-conductor restart
Configuring single-process ironic¶
As an alternative to starting separate API and conductor instances, you can
start ironic
services that combine an API and a conductor in the same
process. This may be particularly beneficial in environments with limited
resources and low number of nodes to handle.
Note
This feature is available starting with the Yoga release series.
Start with setting up the environment as described in both Configuring ironic-api service and Configuring ironic-conductor service, but do not start any services. Merge configuration options into a single configuration file.
Note
Any RPC settings will only take effect if you have more than one combined service started or if you have additional conductors.
If you don’t plan to have more than one conductor, you can disable the RPC completely:
[DEFAULT] rpc_transport = none
Stop existing services if they are already started:
RHEL/CentOS/SUSE:
sudo systemctl stop openstack-ironic-api sudo systemctl stop openstack-ironic-conductor
Ubuntu/Debian:
sudo service ironic-api stop sudo service ironic-conductor stop
Start or restart the ironic service:
RHEL/CentOS/SUSE:
sudo systemctl restart openstack-ironic
Ubuntu/Debian:
sudo service ironic restart