What is the proper way to migrate and upgrade Foreman from 3.3.1 to 3.8.0?

I currently have an instance of Foreman that’s running on CentOS 7 and version 3.3.1. I would like to migrate the instance to AlmaLinux 8.8 and version 3.8.0. What is the proper way to accomplish this? I tried using foreman-maintain to take a full backup, then on a fresh AlmaLinux 8.8 system, I installed a vanilla version of Foreman 3.8.0 then used foreman-maintain there to perform a restore. This somewhat worked, but it was missing all the configurations such as Puppet ENC, hostgroup, networks, compute resources, authentication etc.

Expected outcome:
The foreman-maintain backup and restore should re-create the instance as it was from the source Foreman instance.

Foreman and Proxy versions:

Foreman and Proxy plugin versions:

Distribution and version:

Other relevant data:

instead of migration better i can suggest to go for build new server and install foreman server

I do not recommend doing a new installation if you have not automated it somehow and know where to adjust it for changes made in the last releases.

While on Foreman 3.3 it would run ELevate to update the OS (and migrate to another derivate if you wish): Upgrading and Updating Foreman
Afterwards I would run the Foreman upgrades step by step with a quick verification everything works fine in between.
This may take you a day but is typically faster than doing a rebuild, fixing all the oversights and getting all in afterwards again.

I can say I did this last week with an instance and it went relatively well.

The only technical issue I had outside the typical notes was an issue with a puppet package being listed twice just before the leap upgrade, and that broke my first attempt. VM snapshot saved the day there. My second attempt I updated to puppet7, removed the duplicated package, and did a reinstall on the one version of the package that should exist. I believe this was the puppet-oauth package.

I did this a few months ago. I also had 3.3 on CentOS 7. I upgraded it to CentOS 8 before upgrading foreman further. I had to pretty much uninstall most of the foreman RPMs in order to get the VM to upgrade to CentOS 8. But once that was done, reinstalling foreman on it went well (since all the underlying data was still there and foreman-install put everything that was missing back). Then I upgraded foreman one version at a time until I got to 3.7.

I will probably convert the host to Alma in the future using this conversion script: GitHub - AlmaLinux/almalinux-deploy: EL to AlmaLinux migration tool.

Let me know if this is the route you choose and I’ll find my notes.

Uninstallation of Packages should not be needed, if you follow the instructions I linked above and add the Foreman repos so ELevate does know about. If you can find your notes I would be interested if you missed this step or if something went wrong.

For converting the host to AlmaLinux, I had a similar discussion with a colleague and I would recommend waiting for Foreman supporting EL9 and then decide which route to go when the operating system upgrade is required/possible. Of course if you switched all your systems as a strategic decision just go on and migrate, but if not this will be a good point to make such a decision.

Here’s what I did. I got trapped in some sort of dependency knot, so this is how I eventually got the upgrade from 7 to 8 Stream to complete:


foreman-maintain backup offline --skip-pulp-content --whitelist="sync-plans-enable" /data/foreman/backups
foreman-maintain service stop
foreman-maintain service status -b
tar zcf foreman-etc.tgz /etc/foreman*
systemctl disable puppetdb puppetserver puppet
systemctl stop node_exporter postgres_exporter puppetdb-exporter puppet puppetdb puppetserver
mv /etc/yum.repos.d/redhat.repo /etc/yum.repos.d/runner_gitlab-runner.repo /etc/yum.repos.d/qpid-copr.repo /tmp
yum update --noplugins
# check config of all packages
rpmconf -a
package-cleanup --leaves
yum remove --noplugins $(package-cleanup --leaves --noplugins | sed 's/-[0-9].*$//')
package-cleanup --orphans
yum install -y --noplugins dnf
dnf -y remove yum yum-metadata-parser
dnf update -y
dnf install -y \
  http://vault.centos.org/8.5.2111/BaseOS/x86_64/os/Packages/centos-linux-repos-8-3.el8.noarch.rpm \
  http://vault.centos.org/8.5.2111/BaseOS/x86_64/os/Packages/centos-linux-release-8.5-1.2111.el8.noarch.rpm \
dnf upgrade -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm
dnf remove -y puppet7-release
dnf install -y https://yum.puppetlabs.com/puppet-release-el-8.noarch.rpm
dnf upgrade -y https://yum.theforeman.org/releases/3.3/el8/x86_64/foreman-release.rpm
dnf upgrade -y https://yum.theforeman.org/katello/4.5/katello/el8/x86_64/katello-repos-latest.rpm
dnf clean all
rpm -e `rpm -q kernel`
dnf remove -y sysvinit-tools
dnf remove -y centos-release-scl-rh
dnf remove -y dhclient samba-client-libs samba-common python-syspurpose
dnf install -y centos-release-stream
dnf swap -y centos-{linux,stream}-repos
# reinstall gitlab runner repo
bash script.rpm.sh
sed -i -e 's/el7/el8/g' -e 's/3.2/3.3/g' /etc/yum.repos.d/foreman-client.repo
dnf remove -y redhat-rpm-config python3-rpmconf python2-jmespath
dnf remove -y python36-\*
dnf distro-sync -y --allowerasing
# check for lingering el7 packages and remove them
rpm -qa | grep el7
dnf remove -y $(rpm -qa| grep el7 | awk -F.el7 '{print $1}' | sed 's/-[0-9]\..*$//')
dnf remove -y tomcat-el-2.2-api python3-diff-match-patch mozjs17 python3-packaging \
        tomcat-servlet-3.0-api tomcat-jsp-2.2-api aic94xx-firmware
# install the missing kernel
dnf install -y kernel
# put sssd back
dnf install -y sssd
dnf module -y reset ruby
dnf module -y enable katello:el8 pulpcore:el8 postgresql:12 ruby:2.7
dnf install -y --allowerasing ruby
dnf remove -y python3-whitenoise python3-django
dnf update -y
dnf install foreman-installer-katello
rmdir /etc/yum/protected.d
rm -rf /etc/yum/pluginconf.d
rmdir /etc/yum/vars
dnf install -y yum
cd /
tar zxvf ~/foreman-etc.tgz etc/foreman-installer
# postgres is in new location
systemctl stop postgresql
cd /var/lib
mv pgsql bak.pgsql
cp -a /var/opt/rh/rh-postgresql12/lib/pgsql .
foreman-maintain service status -b
systemctl enable --now puppetdb
systemctl enable --now foreman.socket foreman
puppet agent -t

I did it from centos 7 to Alma 8 with the elevate system it worked easily. The foreman parts upgraded correctly, I had 2 proxies and about 1000 vms. Your issue will be that the foreman repos will be now the archived ones but I guess that can still work

@mattatjgi Thanks, so this looks like you did the manual way via dnf which is not a support way to update. Of course it will work but cause additional manual work introducing more possibilities for something going wrong. This is what Leapp / ELevate is trying to mitigate by showing possible problems in advance and apply solutions automatically where possible.

@stephenc Thanks for also confirming Elevate worked smooth, perhaps we reach the number where people believe that this is a better solution than a re-installation.