Upgrading Foreman to 3.12

Upgrade your Foreman server:

Upgrade your Smart Proxy servers:

If you want to have several smaller outage windows instead of one larger window.

If Smart Proxies in your organization are managed by several teams and are located in different locations.

If you use a load-balanced configuration, you can upgrade one load-balanced Smart Proxy and keep other load-balanced Smart Proxies at one version lower. This allows you to upgrade all Smart Proxies one after another without any outage.

Stop all Foreman services:

# foreman-maintain service stop

Take a snapshot or create a backup:

Start all Foreman services:

# foreman-maintain service start

Optional: If you made manual edits to DNS or DHCP configuration in the /etc/zones.conf or /etc/dhcp/dhcpd.conf files, back up the configuration files because the installer only supports one domain or subnet, and therefore restoring changes from these backups might be required.

Optional: If you made manual edits to DNS or DHCP configuration files and do not want to overwrite the changes, enter the following command:

# foreman-installer \
--foreman-proxy-dhcp-managed=false \
--foreman-proxy-dns-managed=false

In the Foreman web UI, navigate to Hosts > Discovered hosts. On the Discovered Hosts page, power off and then delete the discovered hosts. From the Select an Organization menu, select each organization in turn and repeat the process to power off and delete the discovered hosts. Make a note to reboot these hosts when the upgrade is complete.

Check for running tasks

# foreman-rake katello:upgrade_check

Update operating system packages:

# dnf upgrade

Update repositories

# dnf upgrade https://yum.theforeman.org/releases/3.12/el8/x86_64/foreman-release.rpm \
https://yum.theforeman.org/katello/4.14/katello/el8/x86_64/katello-repos-latest.rpm

Disable the pulpcore module if it is enabled:

# dnf module disable pulpcore

Switch to the PostgreSQL 13 module:

# dnf -y module switch-to postgresql:13

If you are using an external database, upgrade your database to PostgreSQL 13.

Ensure the module streams are enabled:

# dnf module enable katello:el8

Stop all services:

# foreman-maintain service stop

Update the required packages:

# dnf upgrade

Run the installer:

# foreman-installer

Determine if the system needs a reboot:

# dnf needs-restarting --reboothint

If the previous command told you to reboot, then reboot the system:

# reboot

Enter the following command in a tmux window on Foreman server for a pre-migration. This command migrates data while Foreman is running without any need for downtime and reduces future upgrade downtime:

# foreman-maintain advanced procedure run pulpcore-container-handle-image-metadata

If the manifest represents bootable or flatpak content, allow the container image API to display manifest labels, annotations by entering the following command:

# foreman-rake katello:import_container_manifest_labels

Create a backup.

Update repositories:

# dnf upgrade https://yum.theforeman.org/releases/3.12/el8/x86_64/foreman-release.rpm \
https://yum.theforeman.org/katello/4.14/katello/el8/x86_64/katello-repos-latest.rpm

Disable the pulpcore module if it is enabled:

# dnf module disable pulpcore

Switch to the PostgreSQL 13 module:

# dnf -y module switch-to postgresql:13

Ensure the module streams are enabled:

# dnf module enable katello:el8

Update the required packages:

# dnf upgrade

Run the installer:

# foreman-installer

Determine if the system needs a reboot:

# dnf needs-restarting --reboothint

If the previous command told you to reboot, then reboot the system:

# reboot

Optional: If you made manual edits to DNS or DHCP configuration files, check and restore any changes required to the DNS and DHCP configuration files using the backups made earlier.

Create a backup or take a snapshot.

In the Foreman web UI, navigate to Monitor > Jobs.

Click Run Job.

From the Job category list, select Maintenance Operations.

From the Job template list, select Smart Proxy Upgrade Playbook.

In the Search Query field, enter the host name of the Smart Proxy.

Ensure that Apply to 1 host is displayed in the Resolves to field.

In the target_version field, enter the target version of the Smart Proxy.

In the whitelist_options field, enter the options.

Select the schedule for the job execution in Schedule.

In the Type of query section, click Static Query.

Create a backup.

Restore the backup on the new server.

If Foreman reaches the new database server via the old name, no further changes are required. Otherwise reconfigure Foreman to use the new name:

# foreman-installer \
--foreman-db-host newpostgres.example.com \
--katello-candlepin-db-host newpostgres.example.com \
--foreman-proxy-content-pulpcore-postgresql-host newpostgres.example.com

Enable the @theforeman/leapp COPR Repository, which contains Leapp packages with patches to support Foreman or Smart Proxy upgrades:

# dnf copr enable @theforeman/leapp

Install required packages:

# dnf install leapp leapp-upgrade-el8toel9

Install additional packages specific to the operating system (leapp-data-almalinux for AlmaLinux, leapp-data-centos for CentOS Stream, or leapp-data-rocky for Rocky Linux). See ID in /etc/os-release for your operating system code.

# dnf install leapp-data-$ID

Add Foreman specific repositories to /etc/leapp/files/leapp_upgrade_repositories.repo:

[leapp-foreman]
name=Foreman 3.12
baseurl=https://yum.theforeman.org/releases/3.12/el9/$basearch
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-foreman
enabled=1
gpgcheck=1

[leapp-foreman-plugins]
name=Foreman plugins 3.12
baseurl=https://yum.theforeman.org/plugins/3.12/el9/$basearch
enabled=1
gpgcheck=0

[leapp-katello]
name=Katello 4.14
baseurl=https://yum.theforeman.org/katello/4.14/katello/el9/$basearch/
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-foreman
enabled=1
gpgcheck=1

[leapp-candlepin]
name=Candlepin: an open source entitlement management system.
baseurl=https://yum.theforeman.org/candlepin/4.4/el9/$basearch/
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-candlepin
enabled=1
gpgcheck=1

[leapp-pulpcore]
name=pulpcore: Fetch, Upload, Organize, and Distribute Software Packages.
baseurl=https://yum.theforeman.org/pulpcore/3.49/el9/$basearch/
gpgkey=https://yum.theforeman.org/pulpcore/3.49/GPG-RPM-KEY-pulpcore
enabled=1
gpgcheck=1

Append Yum repositories for Puppet to /etc/leapp/files/leapp_upgrade_repositories.repo.

Let Leapp analyze your system:

# leapp preupgrade

Run leapp preupgrade again and make sure that it does not report any more issues.

Let Leapp create the upgrade environment:

# leapp upgrade

Reboot the system to start the upgrade.

Wait for Leapp to finish the upgrade. You can monitor the process with journalctl:

# journalctl -u leapp_resume -f

Verify the post-upgrade state. For more information, see Verifying the post-upgrade state in Upgrading from RHEL 8 to RHEL 9.

Perform post-upgrade tasks on the RHEL 9 system. For more information, see Performing post-upgrade tasks on the RHEL 9 system in Upgrading from RHEL 8 to RHEL 9.

Change SELinux to enforcing mode. For more information, see Changing SELinux mode to enforcing in Upgrading from RHEL 8 to RHEL 9.

For Enterprise Linux installations, unset the subscription-manager release:

# subscription-manager release --unset

Perform a full backup of your Foreman server or Smart Proxy. This is the source Enterprise Linux 8 server that you are migrating. For more information, see Performing a full backup of Foreman server or Smart Proxy server in Administering Foreman.

Deploy a system with Enterprise Linux 9 and the same hostname and configuration as the source server. This is the target server.

Restore the Foreman server or Smart Proxy server backups. For more information, see Restoring Foreman server or Smart Proxy server from a backup in Administering Foreman.