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.