Migrating Red Hat Update Infrastructure

Red Hat Update Infrastructure 4

Migrating to Red Hat Update Infrastructure 4 and upgrading to the latest version of Red Hat Update Infrastructure

Red Hat Customer Content Services

Abstract

This document lists the requirements and provides detailed instructions to help cloud providers migrate to Red Hat Update Infrastructure 4 (RHUI 4). It also provides detailed instructions to upgrade to the latest version of Red Hat Update Infrastructure.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. We are beginning with these four terms: master, slave, blacklist, and whitelist. Because of the enormity of this endeavor, these changes will be implemented gradually over several upcoming releases. For more details, see our CTO Chris Wright’s message.

Chapter 1. Migrating Red Hat Update Infrastructure

After you have installed Red Hat Update Infrastructure (RHUI) 4, it is possible to migrate your existing repositories from RHUI 3 to RHUI 4.

Migration enables RHUI 3 repositories on your RHUI 4 machine. However, it does not migrate the RPM contents or the RPM data. You must re-synchronize these repositories automatically or manually after the migration is complete.

Before you begin the migration process, note the following recommendations and limitations:

  • You cannot upgrade directly from RHUI 3 to RHUI 4. You must install RHUI 4 alongside your current RHUI 3 installation. You can then synchronize the RHUI 3 repositories on RHUI 4 using the same CA certificate from RHUI 3. This also ensures that old clients are able to access content from RHUI 4. Finally, you can change the RHUI 3 load balancer to point to the RHUI 4 CDS nodes.
  • You cannot use LEAPP to upgrade from RHUI 3 to RHUI 4. You must set up RHUI 4 alongside RHUI 3 and then migrate the RHUI data.
  • With RHUI 4, you can use any version of a load balancer, before and after migration. For example, you can use a RHEL 7 version of an HAProxy node from RHUI 3 with a RHUI 4 instance instead of a RHEL 8 version from RHUI 4.

  • To route to two different instances of RHUI, for example a RHUI 3 instance and a RHUI 4 instance, from one address or load balancer, you must set up a RHUI 4 instance so that it can take over all the content from the old RHUI 3 instance.

    However, a configuration where you run both RHUI3 and RHUI4 instances using a single address or a load balancer is not recommended. You can encounter a number of problems ranging from SSL certificate conflicts to repository path changes in between requests.

1.1. Overview of Red Hat Update Infrastructure migration

Migration uses the rhui-manager utility, available in your Red Hat Update Infrastructure (RHUI) 4 installation, to transfer your repositories from RHUI 3 to RHUI 4. You must install RHUI 4 before migrating your repositories.

The rhui-manager utility uses the sub-command migration and the following mandatory arguments:

  1. --hostname - The hostname of the remote RHUI 3 RHUA node
  2. --password - The rhui-manager password of the remote RHUI 3 RHUA node
Note

You must add the public part of an SSH key pair for the current user on the RHUI 4 machine to the .ssh/authorized_keys file on the RHUI 3 machine.

Although a default path is provided, it is likely that the path to your keyfile may not match the provided default. You may have to add the following argument to your migration command:

  • --keyfile_path - The path to the SSH private key on the RHUI 4 machine. The default path is /root/.ssh/id_rsa_rhua.

1.2. Migrating repositories from RHUI 3 to RHUI 4

The following procedure explains how to migrate your RHUI 3 repositories to RHUI 4.

Prerequisites

  • Ensure that RHUI 4 is installed on your destination machine. For more information, see Installing Red Hat Update Infrastructure.
  • Ensure that you have the necessary credentials to access your RHUI 3 machine.

  • Ensure that a RHUI entitlement certificate is available on your RHUI 4 machine. In case it is not, run the following command to add the certificate: 

    # rhui-subscription-sync

  • Optional: Ensure that you have cached the repository information to speed up the migration. You can do so using the following command: 

    # rhui-manager repo unused

Procedure

  1. On your RHUI 4 machine, use the rhui-manager utility to begin the migration: 

    # rhui-manager migrate --hostname my-rhui3-rhua.example.com --password <your_password> --keyfile_path ~/.ssh/id_rsa_rhua

  2. If the migration fails with an error similar to the following, a conflict has occurred between the repositories that you are trying to migrate and those that already exist on your RHUI 4 machine. 

    ERROR: Configured repos detected. Use --force to ignore. Exiting

    To fix this, use the --force argument to run the migration.

    Note

    Using the --force argument deletes and recreates any repositories whose IDs match the RHUI 3 repository IDs. 

    # rhui-manager migrate --hostname my-rhui3-rhua.example.com --password <your_password> --keyfile_path ~/.ssh/id_rsa_rhua --force

  3. Optional: If custom repositories were migrated, you need to manually upload the RPM content to them.

    For detailed instructions on how to do so, see the upload_rpms_document.txt file located in the /root/.rhui/migration/ directory.

Verification

  • Run the following command and verify whether the RHUI 3 repositories are now available on your RHUI 4 machine: 

    # rhui-manager repo list

1.3. Migrating client RPMs from RHUI 3 to RHUI 4

After you upgrade to RHUI 4, you might want to keep using your RHUI 3 client RPMs. You can do so by migrating the RHUI 3 certificate authority (CA) to your RHUI 4 system and and configuring RHUI 4 to use the CA.

Prerequisites

  • Ensure that you have the necessary credentials to access your RHUI 3 machine.

Procedure

  1. Copy the CA certificate and CA key from RHUI 3 to RHUI 4.

    • The certificate, rhui-default-ca.crt, is located in the /etc/pki/rhui/certs/ directory.
    • The key, rhui-default-ca.key, is located in the /etc/pki/rhui/private/ directory.

  2. On the RHUA node, rerun rhui-installer and specify the CA copied from the RHUI 3 installation. 

    # rhui-installer --rerun --remote-fs-server <address> --rhua-hostname <RHUA hostname> --cds-lb-hostname <HAProxy hostname> --user-supplied-rhui-ca-crt rhui-default-ca.crt --user-supplied-rhui-ca-key rhui-default-ca.key
    • --remote-fs-server: The remote mountpoint for the shared file system.
    • --rhua-hostname: The hostname of the RHUA node. You must specify the name as a Fully Qualified Domain Name (FQDN).
    • --cds-lb-hostname: The name of the load balancer that clients use to access the CDS. You must specify the name as a Fully Qualified Domain Name (FQDN).
    • --user-supplied-rhui-ca-crt rhui-default-ca.crt: The CA certificate copied from the RHUI 3 installation.

    • --user-supplied—​rhui-ca-key rhui-default-ca.key: The CA key copied from the RHUI 3 installation.

      Note

      You can use the RHUI 3 HAProxy if it is configured to use the new RHUI 4 CDS nodes. Or, you can use a new RHUI 4 HAProxy by updating the DNS so that the RHUI 3 HAProxy hostname points to the new HAProxy.

Chapter 2. Upgrading Red Hat Update Infrastructure

Red Hat Update Infrastructure (RHUI) is periodically upgraded to introduce bug fixes, enhancements, and fix common vulnerabilities and exposures.

Important

Red Hat recommends keeping your installation up to date by applying the latest RHUI updates when they are released.

2.1. Updating Red Hat Update Infrastructure

To update your instance of Red Hat Update Infrastructure (RHUI) to the latest version, you must update RHUI Manager and the associated packages and nodes.

Prerequisites

  • Root access to the RHUA node.
  • All of your RHUI nodes are subscribed and are using the correct repositories.
  • All previously released errata for Red Hat Enterprise Linux (RHEL) are applied. For more information, see How do I apply package updates to my RHEL system?
  • Repository synchronization tasks are scheduled to run after the update is complete. Tasks that run while the update is in progress might be aborted. For more information see Known Issues.

Procedure

  1. On the RHUA node, update RHUI Installer. 

    # dnf update rhui-installer

  2. Run RHUI Installer:

    • If you are updating from RHUI 4.1.0 or older, you must specify your custom RHUI CA along with the rerun option: 

      # rhui-installer --rerun --user-supplied-rhui-ca-crt <custom_RHUI_CA.crt> --user-supplied-rhui-ca-key <custom_RHUI_CA_key>

    • If you are updating from RHUI 4.1.1 or newer, run RHUI Installer with just the rerun option: 

      # rhui-installer --rerun

  3. Optional: In some environments, rhui-installer fails to rerun and displays the following error instead: 

    There have been identified artifacts with forbidden checksum md5. Run pulpcore-manager handle-artifact-checksums first to unset forbidden checksums.

    To fix this error:

    1. Run the following command on the RHUA node: 

      # env PULP_SETTINGS=/etc/pulp/settings.py pulpcore-manager handle-artifact-checksums
    2. Run rhui-installer with the rerun option.

  4. Check if the rhui-installer installed updated packages.

    By default the rhui-installer will install any available RHEL package updates. RHUA must be rebooted if any package has been updated that requires rebooting. The command to check this is: 

    # needs-restarting -r

  5. To apply updated templates and playbooks, reinstall all of the CDS nodes. 

    # rhui-manager --noninteractive cds reinstall --all

  6. Log in to RHUI Manager. 

    # rhui-manager

Verification

  • On the RHUA node, run the following command and verify whether the latest version of RHUI is installed. 

    # rpm -q rhui-tools

Legal Notice

Copyright © 2024 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.