Using RHUI to configure an in-place upgrade

Updated

The Leapp utility internally contains a list of the most common Red Hat Update Infrastructure (RHUI) setups, for example, RHEL 8 on Amazon Web Services (AWS). If you use a less common RHUI setup unknown to Leapp, you can write a configuration file to supply the Leapp utility with additional or missing information that is required for the in-place upgrade of your system.

Configuring an in-place upgrade with RHUI

You can write a configuration file that provides Leapp with the missing information for an in-place upgrade related to public cloud systems. Clouds that use RHUI to gain repository access have the RHUI client package installed, which is provided by the cloud provider. The RHUI client populates the /etc/yum.repos.d/ file and other system directories with files required to access repositories.

Prerequisites

  • You have the leapp-upgrade-el8toel9 package version 0.22.0 or newer installed on your system.

Procedure

  1. Write a configuration file in the YAML format and store it in /etc/leapp/actor_conf.d/ directory. For example, you can save this file as /etc/leapp/actor_conf.d/rhui.yaml.

IMPORTANT: The file extension must be .yaml, otherwise Leapp ignores the file.

At the top level, you need to define a dictionary with a rhui key that contains the desired RHUI-related configuration. The value of the rhui key is a dictionary that must define the following keys and their corresponding values:

Key Value type Semantics
use_config Boolean If set to True, the declared configuration will be used. Otherwise, the provided RHUI configuration is ignored.
source_clients List of strings A list of RHUI client RPM packages installed on the source system.
target_clients List of strings A list of RHUI client RPM packages that must be installed on the target system in order for the system to have full repository access.
cloud_provider String A string identifying the cloud provider that is hosting the system:
  • If the system is running on AWS, use aws.
  • If the system is running on Microsoft Azure, use azure.
  • If the system is running on a provider other than AWS or Microsoft Azure, use the cloud provider name.
upgrade_files A dictionary from string to string A map that maps file locations on the source system to desired file locations on the target system. The map must contain all files required for the target system to have repository access, for example, repository file definitions, keys, and certificates. Note that the files on the source system must exist.
enabled_target_repositories List of strings A list of target repository IDs to be enabled during the in-place upgrade. These IDs must be defined in the repository files provided in the upgrade_files key.
  1. Proceed by following the upgrade guidelines in the official product documentation.

Configuration file example

The following is an example /etc/leapp/actor_conf.d/rhui.yaml configuration file that enables RHEL 8 to 9 upgrades of Microsoft Azure systems.

NOTE: The Leapp utility already supports upgrades of Microsoft Azure systems. Therefore, this configuration file serves only demonstration purposes.

rhui:
  use_config: True
  source_clients: [ rhui-azure-rhel8 ]
  target_clients: [ rhui-azure-rhel9 ]
  cloud_provider: azure
  upgrade_files:
    - /root/client-contents/key-base.pem : /etc/pki/rhui/private/key-base.pem
    - /root/client-contents/content-base.crt : /etc/pki/rhui/product/content-base.crt
    - /root/client-contents/rh-cloud-base.repo : /etc/yum.repos.d/rh-cloud-base.repo
  rhui_target_repositories_to_use:
    - rhel-9-for-x86_64-baseos-rhui-rpms
    - rhel-9-for-x86_64-appstream-rhui-rpms
    - rhui-microsoft-azure-rhel9

The fields of the configuration file represent the following:

  • source_clients contains the name of the RHUI client on the source system that will be uninstalled during the upgrade process.

  • target_clients contains the name of the RHUI client that must be installed instead of the source client on the upgraded system.

  • cloud_provider contains the name of the cloud provider.

  • upgrade_files contains a list of files necessary to access RHEL 9 packages provided by the RHEL 9 RHUI client. These files are obtained by inspecting a RHEL 9 system running on Microsoft Azure.

  • rhui_target_repositories_to_use contains a list of repository IDs to use during the upgrade process.

Product(s)
Article Type