Chapter 5. Installing undercloud minions
You can deploy additional undercloud minions to scale OpenStack Platform director services across multiple hosts, which helps the performance when you deploy large overclouds. This feature is optional.
This feature is available in this release as a Technology Preview, and therefore is not fully supported by Red Hat. It should only be used for testing, and should not be deployed in a production environment. For more information about Technology Preview features, see Scope of Coverage Details.
5.1. Undercloud minion
An undercloud minion provides additional
ironic-conductor services on a separate host. These additional services support the undercloud with orchestration and provisioning operations. The distribution of undercloud operations across multiple hosts provides more resources to run an overcloud deployment, which can result in potentially faster and larger deployments.
5.2. Undercloud minion requirements
ironic-conductor services on an undercloud minion use a set of workers. Each worker performs operations specific to that service. Multiple workers provide simultaneous operations. The default number of workers on the minion is determined by halving the total CPU thread count of the minion host. In this instance, total thread count is the number of CPU cores multiplied by the hyper-threading value. For example, if your minion has a CPU with 16 threads, then the minion spawns 8 workers for each service by default. The minion also uses a set of minimum and maximum caps by default:
| || |
| || |
An undercloud minion has the following minimum CPU and memory requirements:
- An 8-thread 64-bit x86 processor with support for the Intel 64 or AMD64 CPU extensions. This processor provides 4 workers for each undercloud service.
- A minimum of 16 GB of RAM.
To use a larger number of workers, increase the vCPUs and memory count on the undercloud using a ratio of 2 GB of RAM for each CPU thread. For example, a machine with 48 threads must have 96 GB of RAM. This provides coverage for 24
heat-engine workers and 12
Container image requirements
An undercloud minion does not host an internal container image registry. As a result, you must configure the minion to use one of the following methods to obtain container images:
Pull the images directly from the Red Hat Container Image Registry (
- Pull images that you host on a Red Hat Satellite Server.
For both methods, you must to set
push_destination: false as a part of the
ContainerImagePrepare heat parameter in your
5.3. Preparing a minion
Before you can install a minion, you must complete some basic configuration on the host machine:
- A non-root user to execute commands.
- A resolvable hostname
- A Red Hat subscription
- The command line tools for image preparation and minion installation
Log in to the minion host as the
[root@minion ~]# useradd stack
Set a password for the
[root@minion ~]# passwd stack
Disable password requirements when using
[root@minion ~]# echo "stack ALL=(root) NOPASSWD:ALL" | tee -a /etc/sudoers.d/stack [root@minion ~]# chmod 0440 /etc/sudoers.d/stack
Switch to the new
[root@minion ~]# su - stack [stack@minion ~]$
Check the base and full hostname of the minion:
[stack@minion ~]$ hostname [stack@minion ~]$ hostname -f
If either of the previous commands do not report the correct fully-qualified hostname or report an error, use
hostnamectlto set a hostname:
[stack@minion ~]$ sudo hostnamectl set-hostname minion.example.com [stack@minion ~]$ sudo hostnamectl set-hostname --transient minion.example.com
/etc/hostsfile and include an entry for the system hostname. For example, if the system is named
minion.example.comand uses the IP address
10.0.0.1, add the following line to the
10.0.0.1 minion.example.com manager
Register your system either with the Red Hat Content Delivery Network or Red Hat Satellite. For example, run the following command to register the system to the Content Delivery Network. Enter your Customer Portal user name and password when prompted:
[stack@minion ~]$ sudo subscription-manager register
Find the entitlement pool ID for Red Hat OpenStack Platform (RHOSP) director:
[stack@minion ~]$ sudo subscription-manager list --available --all --matches="Red Hat OpenStack" Subscription Name: Name of SKU Provides: Red Hat Single Sign-On Red Hat Enterprise Linux Workstation Red Hat CloudForms Red Hat OpenStack Red Hat Software Collections (for RHEL Workstation) Red Hat Virtualization SKU: SKU-Number Contract: Contract-Number Pool ID: Valid-Pool-Number-123456 Provides Management: Yes Available: 1 Suggested: 1 Service Level: Support-level Service Type: Service-Type Subscription Type: Sub-type Ends: End-date System Type: Physical
Pool IDvalue and attach the Red Hat OpenStack Platform 16.1 entitlement:
[stack@minion ~]$ sudo subscription-manager attach --pool=Valid-Pool-Number-123456
Disable all default repositories, and then enable the required Red Hat Enterprise Linux repositories:
[stack@minion ~]$ sudo subscription-manager repos --disable=* [stack@minion ~]$ sudo subscription-manager repos --enable=rhel-8-for-x86_64-baseos-eus-rpms --enable=rhel-8-for-x86_64-appstream-eus-rpms --enable=rhel-8-for-x86_64-highavailability-eus-rpms --enable=ansible-2.9-for-rhel-8-x86_64-rpms --enable=openstack-16.1-for-rhel-8-x86_64-rpms --enable=fast-datapath-for-rhel-8-x86_64-rpms
These repositories contain packages that the minion installation requires.
Perform an update on your system to ensure that you have the latest base system packages:
[stack@minion ~]$ sudo dnf update -y [stack@minion ~]$ sudo reboot
Install the command line tools for minion installation and configuration:
[stack@minion ~]$ sudo dnf install -y python3-tripleoclient
5.4. Copying the undercloud configuration files to the minion
The minion requires some configuration files from the undercloud so that the minion installation can configure the minion services and register them with director:
Log in to your undercloud as the
Copy the files from the undercloud to the minion:
$ scp ~/tripleo-undercloud-outputs.yaml ~/tripleo-undercloud-passwords.yaml stack@<minion-host>:~/.
<minion-host>with the hostname or IP address of the minion.
5.6. Configuring the minion
The minion installation process requires certain settings in the
minion.conf configuration file, which the minion reads from the home directory of the
stack user. Complete the following steps to use the default template as a foundation for your configuration.
Log in to the minion host as the
Copy the default template to the home directory of the
[stack@minion ~]$ cp \ /usr/share/python-tripleoclient/minion.conf.sample \ ~/minion.conf
minion.conffile. This file contains settings to configure your minion. If you omit or comment out a parameter, the minion installation uses the default value. Review the following recommended parameters:
minion_hostname, which you set to the hostname of the minion.
minion_local_interface, which you set to the interface that connects to the undercloud through the Provisioning Network.
minion_local_ip, which you set to a free IP address on the Provisioning Network.
minion_nameservers, which you set to the DNS nameservers so that the minion can resolve hostnames.
enable_ironic_conductor, which defines whether to enable the
enable_heat_engine, which defines whether to enable the
minion.conf file enables only the
heat-engine service on the minion. To enable the
ironic-conductor service, set the
enable_ironic_conductor parameter to
5.7. Minion configuration parameters
The following list contains information about parameters for configuring the
minion.conf file. Keep all parameters within their relevant sections to avoid errors.
The following parameters are defined in the
[DEFAULT] section of the
Cleanup temporary files. Set this parmaeter to
Falseto leave the temporary files used during deployment in place after the command is run. This is useful for debugging the generated files or if errors occur.
The CLI tool for container management. Leave this parameter set to
podman. Red Hat Enterprise Linux 8.2 only supports
Disables containerized service health checks. Red Hat recommends that you enable health checks and leave this option set to
Heat environment file with container image information. This file can contain the following entries:
- Parameters for all required container images
ContainerImagePrepareparameter to drive the required image preparation. Usually the file that contains this parameter is named
A list of insecure registries for
podmanto use. Use this parameter if you want to pull images from another source, such as a private container registry. In most cases,
podmanhas the certificates to pull container images from either the Red Hat Container Catalog or from your Satellite server if the minion is registered to Satellite.
- Additional environment file that you want to add to the minion installation.
The user who installs the minion. Leave this parameter unset to use the current default user
Defines whether to install the heat engine on the minion. The default is
Defines whether to install the ironic conductor service on the minion. The default value is
false. Set this value to
trueto enable the ironic conductor service.
- URL for the heat container image that you want to use. Leave unset.
Use native heat templates. Leave as
hieradataoverride file that configures Puppet hieradata on the director, providing custom configuration to services beyond the
minion.confparameters. If set, the minion installation copies this file to the
/etc/puppet/hieradatadirectory and sets it as the first file in the hierarchy.
Set this value to
trueto enable the
DEBUGlog level for minion services.
Enable or disable SELinux during the deployment. It is highly recommended to leave this value set to
trueunless you are debugging an issue.
- Enable validation services on the minion.
- Defines the fully qualified host name for the minion. If set, the minion installation configures all system host name settings. If left unset, the minion uses the current host name, but you must configure all system host name settings appropriately.
The chosen interface for the Provisioning NIC on the undercloud. This is also the device that the minion uses for DHCP and PXE boot services. Change this value to your chosen device. To see which device is connected, use the
ip addrcommand. For example, this is the result of an
2: eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP qlen 1000 link/ether 52:54:00:75:24:09 brd ff:ff:ff:ff:ff:ff inet 192.168.122.178/24 brd 192.168.122.255 scope global dynamic eth0 valid_lft 3462sec preferred_lft 3462sec inet6 fe80::5054:ff:fe75:2409/64 scope link valid_lft forever preferred_lft forever 3: eth1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noop state DOWN link/ether 42:0b:c2:a5:c1:26 brd ff:ff:ff:ff:ff:ff
In this example, the External NIC uses
eth0and the Provisioning NIC uses
eth1, which is currently not configured. In this case, set the
eth1. The configuration script attaches this interface to a custom bridge defined with the
The IP address defined for the Provisioning NIC on the undercloud. This is also the IP address that the minion uses for DHCP and PXE boot services. Leave this value as the default
192.168.24.1/24unless you use a different subnet for the Provisioning network, for example, if the default IP address conflicts with an existing IP address or subnet in your environment.
The maximum transmission unit (MTU) that you want to use for the
local_interface. Do not exceed 1500 for the minion.
The path to a log file where you want to store the minion install and upgrade logs. By default, the log file is
install-minion.login the home directory. For example,
- A list of DNS nameservers to use for the minion hostname resolution.
- A list of network time protocol servers to help synchronize the minion date and time.
The file that contains the passwords for the minion to connect to undercloud services. Leave this parameter set to the
tripleo-undercloud-passwords.yamlfile copied from the undercloud.
- The location and filename of the certificate for OpenStack SSL/TLS communication. Ideally, you obtain this certificate from a trusted certificate authority. Otherwise, generate your own self-signed certificate.
- Host timezone for the minion. If you do not specify a timezone, the minion uses the existing timezone configuration.
The file that contains undercloud configuration information that the minion can use to connect to undercloud services. Leave this parameter set to the
tripleo-undercloud-outputs.yamlfile copied from the undercloud.
The path to a network configuration override template. If you set this parameter, the minion uses a JSON format template to configure the networking with
os-net-configand ignores the network parameters set in
/usr/share/python-tripleoclient/minion.conf.samplefor an example.
Networks file to override for
- Directory to output state, processed heat templates, and Ansible deployment files.
- The roles file that you want to use to override the default roles file for minion installation. It is highly recommended to leave this parameter unset so that the minion installation uses the default roles file.
- Heat templates file to override.
5.8. Installing the minion
Complete the following steps to install the minion.
Log in to the minion host as the
Run the following command to install the minion:
[stack@minion ~]$ openstack undercloud minion install
This command launches the configuration script for the minion, installs additional packages, and configures minion services according to the configuration in the
minion.conffile. This script takes several minutes to complete.
5.9. Verifying the minion installation
Complete the following steps to confirm a successful minion installation.
Log in to your undercloud as the
[stack@director ~]$ source ~/stackrc
If you enabled the heat engine service on the minion, verify that the
heat-engineservice from the minion appears on the undercloud service list:
[stack@director ~]$ $ openstack orchestration service list
The command output displays a table with
heat-engineworkers for both the undercloud and any minions.
If you enabled the ironic conductor service on the minion, verify that the
ironic-conductorservice from the minion appears on the undercloud service list:
[stack@director ~]$ $ openstack baremetal conductor list
The command output displays a table with
ironic-conductorservices for both the undercloud and any minions.
5.10. Next Steps
- Perform basic overcloud configuration, including registering nodes, inspecting nodes, and tagging nodes into various node roles. For more information, see Chapter 7, Configuring a basic overcloud with CLI tools.