Chapter 5. Installing undercloud minions

Important

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 heat-engine and 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

The scaled heat-engine and 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:

ServiceMinimumMaximum

heat-engine

4

24

ironic-conductor

2

12

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 ironic-conductor workers.

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

Procedure

  1. Log in to the minion host as the root user.
  2. Create the stack user:

    [root@minion ~]# useradd stack
  3. Set a password for the stack user:

    [root@minion ~]# passwd stack
  4. Disable password requirements when using sudo:

    [root@minion ~]# echo "stack ALL=(root) NOPASSWD:ALL" | tee -a /etc/sudoers.d/stack
    [root@minion ~]# chmod 0440 /etc/sudoers.d/stack
  5. Switch to the new stack user:

    [root@minion ~]# su - stack
    [stack@minion ~]$
  6. 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 hostnamectl to set a hostname:

    [stack@minion ~]$ sudo hostnamectl set-hostname minion.example.com
    [stack@minion ~]$ sudo hostnamectl set-hostname --transient minion.example.com
  7. Edit the /etc/hosts file and include an entry for the system hostname. For example, if the system is named minion.example.com and uses the IP address 10.0.0.1, add the following line to the /etc/hosts file:

    10.0.0.1  minion.example.com manager
  8. 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
  9. 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
  10. Locate the Pool ID value and attach the Red Hat OpenStack Platform 16.0 entitlement:

    [stack@minion ~]$ sudo subscription-manager attach --pool=Valid-Pool-Number-123456
  11. 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-rpms --enable=rhel-8-for-x86_64-highavailability-eus-rpms --enable=ansible-2.8-for-rhel-8-x86_64-rpms --enable=openstack-16-for-rhel-8-x86_64-rpms --enable=fast-datapath-for-rhel-8-x86_64-rpms

    These repositories contain packages that the minion installation requires.

  12. 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
  13. 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:

  • tripleo-undercloud-outputs.yaml
  • tripleo-undercloud-passwords.yaml

Procedure

  1. Log in to your undercloud as the stack user.
  2. Copy the files from the undercloud to the minion:

    $ scp ~/tripleo-undercloud-outputs.yaml ~/tripleo-undercloud-passwords.yaml stack@<minion-host>:~/.

    Replace <minion-host> with the hostname or IP address of the minion.

5.5. Copying the undercloud certificate authority

If the undercloud uses SSL/TLS for endpoint encryption, the minion host must contain the certificate authority that signed the undercloud SSL/TLS certificates. Depending on your undercloud configuration, this certificate authority is one of the following:

  • An external certificate authority whose certificate is preloaded on the minion host. No action is required.
  • A director-generated self-signed certificate authority, which the director creates at /etc/pki/ca-trust/source/anchors/cm-local-ca.pem. Copy this file to the minion host and include the file as a part of the trusted certificate authorities for the minion host. This procedure uses this file as an example.
  • A custom self-signed certificate authority, which you create with OpenSSL. Examples in this document refer to this file as ca.crt.pem. Copy this file to the minion host and include the file as a part of the trusted certificate authorities for the minion host.

Procedure

  1. Log in to the minion host as the root user.
  2. Copy the certificate authority file from the undercloud to the minion:

    [root@minion ~]# scp \
        root@<undercloud-host>:/etc/pki/ca-trust/source/anchors/cm-local-ca.pem \
        /etc/pki/ca-trust/source/anchors/undercloud-ca.pem

    Replace <undercloud-host> with the hostname or IP address of the undercloud.

  3. Update the trusted certificate authorities for the minion host:

    [root@minion ~]# update-ca-trust enable
    [root@minion ~]# update-ca-trust extract

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.

Procedure

  1. Log in to the minion host as the stack user.
  2. Copy the default template to the home directory of the stack user:

    [stack@minion ~]$ cp \
      /usr/share/python-tripleoclient/minion.conf.sample \
      ~/minion.conf
  3. Edit the minion.conf file. 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 ironic-conductor service.
    • enable_heat_engine, which defines whether to enable the heat-engine service.
Note

The default 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 true.

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.

Defaults

The following parameters are defined in the [DEFAULT] section of the minion.conf file:

cleanup
Cleanup temporary files. Set this parmaeter to False to 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.
container_cli
The CLI tool for container management. Leave this parameter set to podman. Red Hat Enterprise Linux 8.1 only supports podman.
container_healthcheck_disabled
Disables containerized service health checks. Red Hat recommends that you enable health checks and leave this option set to false.
container_images_file

Heat environment file with container image information. This file can contain the following entries:

  • Parameters for all required container images
  • The ContainerImagePrepare parameter to drive the required image preparation. Usually the file that contains this parameter is named containers-prepare-parameter.yaml.
container_insecure_registries
A list of insecure registries for podman to use. Use this parameter if you want to pull images from another source, such as a private container registry. In most cases, podman has 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.
container_registry_mirror
An optional registry-mirror configured that podman uses.
custom_env_files
Additional environment file that you want to add to the minion installation.
deployment_user
The user who installs the minion. Leave this parameter unset to use the current default user stack.
enable_heat_engine
Defines whether to install the heat engine on the minion. The default is true.
enable_ironic_conductor
Defines whether to install the ironic conductor service on the minion. The default value is false. Set this value to true to enable the ironic conductor service.
heat_container_image
URL for the heat container image that you want to use. Leave unset.
heat_native
Use native heat templates. Leave as true.
hieradata_override
Path to hieradata override file that configures Puppet hieradata on the director, providing custom configuration to services beyond the minion.conf parameters. If set, the minion installation copies this file to the /etc/puppet/hieradata directory and sets it as the first file in the hierarchy.
minion_debug
Set this value to true to enable the DEBUG log level for minion services.
minion_enable_selinux
Enable or disable SELinux during the deployment. It is highly recommended to leave this value set to true unless you are debugging an issue.
minion_enable_validations
Enable validation services on the minion.
minion_hostname
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.
minion_local_interface

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 addr command. For example, this is the result of an ip addr command:

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 eth0 and the Provisioning NIC uses eth1, which is currently not configured. In this case, set the local_interface to eth1. The configuration script attaches this interface to a custom bridge defined with the inspection_interface parameter.

minion_local_ip
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/24 unless 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.
minion_local_mtu
The maximum transmission unit (MTU) that you want to use for the local_interface. Do not exceed 1500 for the minion.
minion_log_file
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.log in the home directory. For example, /home/stack/install-minion.log.
minion_nameservers
A list of DNS nameservers to use for the minion hostname resolution.
minion_ntp_servers
A list of network time protocol servers to help synchronize the minion date and time.
minion_password_file
The file that contains the passwords for the minion to connect to undercloud services. Leave this parameter set to the tripleo-undercloud-passwords.yaml file copied from the undercloud.
minion_service_certificate
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.
minion_timezone
Host timezone for the minion. If you do not specify a timezone, the minion uses the existing timezone configuration.
minion_undercloud_output_file
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.yaml file copied from the undercloud.
net_config_override
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-config and ignores the network parameters set in minion.conf. See /usr/share/python-tripleoclient/minion.conf.sample for an example.
networks_file
Networks file to override for heat.
output_dir
Directory to output state, processed heat templates, and Ansible deployment files.
roles_file
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.
templates
Heat templates file to override.

5.8. Installing the minion

Complete the following steps to install the minion.

Procedure

  1. Log in to the minion host as the stack user.
  2. 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.conf file. This script takes several minutes to complete.

5.9. Verifying the minion installation

Complete the following steps to confirm a successful minion installation.

Procedure

  1. Log in to your undercloud as the stack user.
  2. Source the stackrc file:

    [stack@director ~]$ source ~/stackrc
  3. If you enabled the heat engine service on the minion, verify that the heat-engine service from the minion appears on the undercloud service list:

    [stack@director ~]$ $ openstack orchestration service list

    The command output displays a table with heat-engine workers for both the undercloud and any minions.

  4. If you enabled the ironic conductor service on the minion, verify that the ironic-conductor service from the minion appears on the undercloud service list:

    [stack@director ~]$ $ openstack baremetal conductor list

    The command output displays a table with ironic-conductor services for both the undercloud and any minions.

5.10. Next Steps