Skip to content

Commit

Permalink
Rewrite upgrade steps using an OS selector
Browse files Browse the repository at this point in the history 
This copies the OS selector from the quickstart. This makes the upgrade
instructions shorter since you don't need to skip over irrelevant OSes.
For users this is less confusing.

It also removes the foreman-maintain reference. This can be done by
moving the cleanup step to a point where the services should be stopped
anyway. Avoiding a start-stop cycle makes the overall process shorter.

The noop command removes the redundant --dont-save-answers. --noop
already implies that.
  • Loading branch information
@ekohl
ekohl committed Mar 11, 2021
1 parent 845ffb2 commit 8572535
Show file tree
Hide file tree
Showing 2 changed files with 298 additions and 140 deletions.
219 changes: 149 additions & 70 deletions _includes/manuals/2.4/3.6_upgrade.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,30 @@ when planning to upgrade, as these change between releases. If your OS is no
longer supported by Foreman, migrate or upgrade the OS (if supported) using a
release of Foreman supported by both OS versions before upgrading Foreman.

<script type="text/javascript">
function update_upgrade_os(select) {
var os = select.value;
$(".upgrade_os").hide();
if (os) {
$(".upgrade_os_"+os).show();
} else {
$(".upgrade_os_none").show();
}
}
$(document).ready(function() {
$('#upgrade_os').trigger('change');
});
</script>

To provide specific installation instructions, please select your operating system:
<select id="upgrade_os" onChange="update_upgrade_os(this);">
<option value="none">-- select operating system --</option>
<option value="el7">CentOS 7 / Red Hat Enterprise Linux 7</option>
<option value="el8">CentOS 8 / Red Hat Enterprise Linux 8</option>
<option value="debian10">Debian 10 (Buster)</option>
<option value="ubuntu1804">Ubuntu 18.04 (Bionic)</option>
</select>

#### Step 1 - Backup

It is recommended that you backup your database and modifications to Foreman
Expand All @@ -28,74 +52,117 @@ For more information about how to backup your instance head over to

#### Step 2 - Perform the upgrade

Before proceeding, it is necessary to shutdown the Foreman instance (e.g.
`systemctl stop httpd foreman.service foreman.socket` or
`systemctl stop apache foreman.service foreman.socket` usually).

Now it's time to perform the actual upgrade. This process if different
depending on how you downloaded Foreman. You only need to perform *one* of
the following options.

##### Step 2 (A) - RHEL package (RPM) and installer setups

Before proceeding, it is necessary to shutdown the Foreman instance.

<div class="upgrade_os upgrade_os_none">
<i>No operating system selected.</i>
</div>
<div class="upgrade_os upgrade_os_el7 upgrade_os_el8">
{% highlight bash %}
systemctl stop httpd foreman.service foreman.socket
{% endhighlight %}
</div>
<div class="upgrade_os upgrade_os_debian10 upgrade_os_ubuntu1804">
{% highlight bash %}
systemctl stop apache foreman.service foreman.socket
{% endhighlight %}
</div>

Now it's time to perform the actual upgrade.

<div class="upgrade_os upgrade_os_none">
<i>No operating system selected.</i>
</div>

<div class="upgrade_os upgrade_os_el7">
To upgrade an existing Foreman installation, first update with the
appropriate foreman-release package for your operating system:
appropriate foreman-release package:

yum upgrade https://yum.theforeman.org/releases/{{page.version}}/el7/x86_64/foreman-release.rpm
{% highlight bash %}
yum upgrade https://yum.theforeman.org/releases/{{page.version}}/el7/x86_64/foreman-release.rpm
{% endhighlight %}

Clean up the yum metadata cache:
Also make sure centos-release-scl-rh is up to date:

yum clean metadata
{% highlight bash %}
yum upgrade centos-release-scl-rh
{% endhighlight %}

First install or upgrade the SCL release packages to add the RHSCL repository:

yum install centos-release-scl-rh
Clean up the yum metadata cache:

or:
{% highlight bash %}
yum clean metadata
{% endhighlight %}

yum upgrade centos-release-scl-rh
Next upgrade all Foreman packages:

Clean up the yum metadata cache once more, to ensure the new repositories are used:
{% highlight bash %}
yum upgrade tfm\* ruby\* foreman\*
{% endhighlight %}

yum clean metadata
Optionally, consider removing unused SCL packages:

Next upgrade all Foreman packages:
{% highlight bash %}
yum erase rh-ruby22\* rh-ruby24\* rh-ror42\* tfm-ror52\*
{% endhighlight %}
</div>

yum upgrade tfm\* ruby\* foreman\*
<div class="upgrade_os upgrade_os_el8">
To upgrade an existing Foreman installation, first update with the
appropriate foreman-release package:

{% highlight bash %}
dnf upgrade https://yum.theforeman.org/releases/{{page.version}}/el8/x86_64/foreman-release.rpm
{% endhighlight %}

In order to catch all configuration changes and manage them properly you should install and run
rpmconf from the EPEL repository along with vim-enhanced (for vimdiff):
Clean up the yum metadata cache:

rpmconf -a --frontend=vimdiff
{% highlight bash %}
dnf clean metadata
{% endhighlight %}

You can skip to Step 3.
Next upgrade all Foreman packages:

##### Step 2 (B) - Debian or Ubuntu package (deb) and installer setups
{% highlight bash %}
dnf upgrade ruby\* foreman\*
{% endhighlight %}
</div>

Upgrading from the last release to {{page.version}} has been tested on both
Debian and Ubuntu. Updating the packages will upgrade the application and
automatically migrate the database.
<div class="upgrade_os upgrade_os_debian10 upgrade_os_ubuntu1804">
Upgrading from the last release to {{page.version}} has been tested. Updating
the packages will upgrade the application and automatically migrate the
database.

First edit `/etc/apt/sources.list.d/foreman.list` and change the release
number from the previous release or "stable" to `{{ page.version }}`:

deb http://deb.theforeman.org/ buster {{ page.version }}
deb http://deb.theforeman.org/ plugins {{ page.version }}
number from the previous release to `{{ page.version }}`:

<div class="upgrade_os upgrade_os_debian10">
{% highlight bash %}
deb http://deb.theforeman.org/ buster {{ page.version }}
deb http://deb.theforeman.org/ plugins {{ page.version }}
{% endhighlight %}
</div>
<div class="upgrade_os upgrade_os_ubuntu1804">
{% highlight bash %}
deb http://deb.theforeman.org/ bionic {{ page.version }}
deb http://deb.theforeman.org/ plugins {{ page.version }}
{% endhighlight %}
</div>

Next upgrade all Foreman packages:

apt-get update
apt-get --only-upgrade install ruby\* foreman\*

You can skip to Step 3.
{% highlight bash %}
apt-get update
apt-get --only-upgrade install ruby\* foreman\*
{% endhighlight %}
</div>

#### Step 3 - Post-upgrade steps

##### Step 3 (A) - Database migration and cleanup

The database should be migrated already, but you can make sure by executing the
migration script again, it should produce no errors or output:
Make sure by executing database is migrated. It should produce no errors or
output:

foreman-rake db:migrate
foreman-rake db:seed
Expand All @@ -105,7 +172,13 @@ You should clear the cache and the existing sessions:
foreman-rake tmp:cache:clear
foreman-rake db:sessions:clear

##### Optional Step 3 (B) - Run foreman-installer
##### Optional Step 3 (B) - Reclaim database space

After database migrations, some space can sometimes be reclaimed. It's a good idea to perform a *full* database vacuum for PostgreSQL rather than relying on the autovacuum feature to claim maximum space possible.

su - postgres -c 'vacuumdb --full --dbname=foreman'

##### Optional Step 3 (C) - Run foreman-installer

If you used foreman-installer to set up your existing Foreman instance we
recommend running it again after upgrading. Note that the installer can
Expand All @@ -114,41 +187,47 @@ the installer in noop mode so you can see what would be changed.

To see what would happen

foreman-installer --noop --dont-save-answers --verbose
foreman-installer --noop --verbose

You may see ERRORS such as `/Stage[main]/Foreman_proxy::Register/Foreman_smartproxy[foreman-hostname.domain]:` `Could not evaluate: Connection refused - connect(2)` due to httpd / apache2 service being stopped. These can be safely ignored.

To apply these changes, run the installer again without options

foreman-installer

#### Step 4 - Restart

Restart the application server (e.g. mongrel, thin, passenger).

On RPM installations, run:

systemctl start httpd foreman.service foreman.socket

And on Debian/Ubuntu installations, run:

systemctl start apache foreman.service foreman.socket

#### Optional Step 5 - Reclaim database space

After database migrations, some space can sometimes be reclaimed. It's a good idea to perform a *full* database vacuum for PostgreSQL rather than relying on the autovacuum feature to claim maximum space possible. For PostgreSQL do the following:

foreman-maintain service stop --exclude postgresql
su - postgres -c 'vacuumdb --full --dbname=foreman'
foreman-maintain service start

On platforms where foreman-maintain is not available, stop all Foreman-related services except PostgreSQL.

#### Optional Step 6 - Cleanup of RPMs and repositories

On EL7, consider removing unused SCL packages:

yum erase rh-ruby22\* rh-ruby24\* rh-ror42\* tfm-ror52\*
##### Optional Step 3 (D) - Update config files
<div class="upgrade_os upgrade_os_none">
<i>*No operating system selected.*</i>
</div>
<div class="upgrade_os upgrade_os_el7">
In order to catch all configuration changes and manage them properly you should install and run
rpmconf from the EPEL repository along with vim-enhanced (for vimdiff).

{% highlight bash %}
rpmconf -a --frontend=vimdiff
{% endhighlight %}
</div>
<div class="upgrade_os upgrade_os_el8 upgrade_os_debian10 upgrade_os_ubuntu1804">
This step is irrelevant for the chosen operating system.
</div>

##### Step 4 - Restart

Start the application server. This is redundant if you previously ran `foreman-installer` in step 3B.

<div class="upgrade_os upgrade_os_none">
<i>*No operating system selected.*</i>
</div>
<div class="upgrade_os upgrade_os_el7 upgrade_os_el8">
{% highlight bash %}
systemctl start httpd foreman.service foreman.socket
{% endhighlight %}
</div>
<div class="upgrade_os upgrade_os_debian10 upgrade_os_ubuntu1804">
{% highlight bash %}
systemctl start apache foreman.service foreman.socket
{% endhighlight %}
</div>

#### Common issues

Expand Down
Loading

0 comments on commit 8572535

Please sign in to comment.