Chapter 8. Configuring the overcloud for a Leapp upgrade

You must complete some Leapp configuration to prepare for the overcloud upgrade.

8.1. Creating an upgrades environment file

The upgrade process uses an environment file to enable the upgrade process and configure specific upgrade parameters.


  1. Log in to the undercloud as the stack user.
  2. Create an environment file called upgrades-environment.yaml in your templates directory:

    $ touch templates/upgrades-environment.yaml
  3. Edit the file and add the following mandatory content:

      UpgradeInitCommand: |
        sudo dnf module disable -y container-tools:rhel8
        sudo dnf module enable -y container-tools:2.0
        sudo dnf module disable -y virt:rhel
        sudo dnf module enable -y virt:8.2
      UpgradeLeappCommandOptions: "--enablerepo rhel-8-for-x86_64-baseos-eus-rpms --enablerepo rhel-8-for-x86_64-appstream-eus-rpms --enablerepo fast-datapath-for-rhel-8-x86_64-rpms"
    • UpgradeInitCommand sets a series of bash commands to run that director runs before starting the upgrade on a node. In this context, set this parameter to use the dnf commands to switch from the default container-tools:rhel8 module to container-tools:2.0.
    • UpgradeLeappCommandOptions sets additional options to pass to the Leapp tool. In this context, set this parameter to enable Red Hat OpenStack Platform repositories to help with the Leapp transition.
  4. Save the upgrades-environment.yaml file.

8.2. Upgrade parameters



Command or script snippet to run on all overcloud nodes to initialize the upgrade process. For example, a repository switch.


Common commands required by the upgrades process. This should not normally be modified by the operator and is set and unset in the major-upgrade-composable-steps.yaml and major-upgrade-converge.yaml environment files.


Additional command line options to append to the Leapp command.


Print debugging output when running Leapp. The default value is True.


Skip Leapp checks by setting env variables when running Leapp in development/testing. For example, LEAPP_DEVEL_SKIP_RHSM=1.


Use Leapp for operating system upgrade. The default value is False.


Timeout (seconds) for the OS upgrade phase via Leapp. The default value is 3600.


List of packages to install after Leapp upgrade.


List of packages to remove during Leapp upgrade.

8.3. Copying the Leapp data to the overcloud nodes

Each overcloud node requires the Leapp data files. The director automatically copies the data files in the /etc/leapp/files directory on the undercloud to the same location on each overcloud. Check that the pes-events.json and repomap.csv files still exist in the /etc/leapp/files directory of the undercloud:


  1. Log in to the undercloud as the stack user.
  2. Check the /etc/leapp/files directory on the undercloud:

    $ sudo ls /etc/leapp/files/

If these files were removed, download these files attached to the Knowledge Base article "Data required by the Leapp utility for an in-place upgrade from RHEL 7 to RHEL 8" and place these files in the /etc/leapp/files/ directory on the undercloud.

8.4. Using predictable NIC names for overcloud nodes

Before you run the Leapp upgrade on overcloud nodes, you must check for kernel-based NIC names, which usually contain a eth prefix. These NIC names are usually unpredictable in terms of NIC assignments. The Leapp upgrade fails if any NICs on the node use the eth prefix.


  • The playbook-nics.yaml playbook created during the undercloud preparation process. The playbook-nics.yaml playbook accommodates most overcloud networking scenarios that use Ethernet devices, bridges, and Linux bonds. If your environment requires additional configuration beyond these device types, follow these recommendations before proceeding:

    • Test the playbook on a separate system with a similar networking configuration to your overcloud nodes
    • Modify the playbook to accommodate renaming the eth prefix within the configuration of other device types
    • Check the networking configuration of your overcloud nodes after you complete this procedure


  1. Log in to the undercloud as the stack user.
  2. Run the playbook-nics.yaml playbook on all overcloud nodes:

    $ ansible-playbook -i ~/inventory.yaml playbook-nics.yaml

    The playbook sets the new NIC prefix to em. To set a different NIC prefix, set the prefix variable when running the playbook:

    $ ansible-playbook -i ~/inventory.yaml -e prefix="mynic" playbook-nics.yaml
  3. Reboot overcloud nodes using the standard reboot procedures. For more information, see "Rebooting nodes".

8.5. Setting the SSH root permission parameter on the overcloud

The Leapp upgrade checks whether the PermitRootLogin parameter exists in the /etc/ssh/sshd_config file on each node. You must explicitly set this parameter to either yes or no.

For security purposes, set this parameter to no to disable SSH access to the root user on overcloud nodes.


  • An Ansible inventory file for your overcloud nodes.


  1. Log in to the undercloud as the stack user.
  2. Create a file called playbook-ssh.yaml and paste the following content in the file:

    - name: Configure SSH PermitRootLogin parameter
      hosts: overcloud
      become: yes
        - name: Set the PermitRootLogin parameter to no
            path: /etc/ssh/sshd_config
            state: present
            line: "PermitRootLogin no"
  3. Run the playbook:

    $ ansible-playbook -i ~/inventory.yaml playbook-ssh.yaml