From 8572535ebcbac66223460a6144cf7356d7ff7a1e Mon Sep 17 00:00:00 2001 From: Ewoud Kohl van Wijngaarden Date: Thu, 4 Mar 2021 11:16:39 +0100 Subject: [PATCH] Rewrite upgrade steps using an OS selector 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. --- _includes/manuals/2.4/3.6_upgrade.md | 219 +++++++++++++++-------- _includes/manuals/nightly/3.6_upgrade.md | 219 +++++++++++++++-------- 2 files changed, 298 insertions(+), 140 deletions(-) diff --git a/_includes/manuals/2.4/3.6_upgrade.md b/_includes/manuals/2.4/3.6_upgrade.md index 27ac5561f7..3464950be6 100644 --- a/_includes/manuals/2.4/3.6_upgrade.md +++ b/_includes/manuals/2.4/3.6_upgrade.md @@ -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. + + +To provide specific installation instructions, please select your operating system: + + #### Step 1 - Backup It is recommended that you backup your database and modifications to Foreman @@ -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. + +
+ No operating system selected. +
+
+{% highlight bash %} +systemctl stop httpd foreman.service foreman.socket +{% endhighlight %} +
+
+{% highlight bash %} +systemctl stop apache foreman.service foreman.socket +{% endhighlight %} +
+ +Now it's time to perform the actual upgrade. + +
+ No operating system selected. +
+ +
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 %} +
- yum upgrade tfm\* ruby\* foreman\* +
+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 %} +
-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. +
+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 }}`: + +
+{% highlight bash %} +deb http://deb.theforeman.org/ buster {{ page.version }} +deb http://deb.theforeman.org/ plugins {{ page.version }} +{% endhighlight %} +
+
+{% highlight bash %} +deb http://deb.theforeman.org/ bionic {{ page.version }} +deb http://deb.theforeman.org/ plugins {{ page.version }} +{% endhighlight %} +
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 %} +
#### 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 @@ -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 @@ -114,7 +187,7 @@ 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. @@ -122,33 +195,39 @@ 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 +
+ *No operating system selected.* +
+
+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 %} +
+
+This step is irrelevant for the chosen operating system. +
+ +##### Step 4 - Restart + +Start the application server. This is redundant if you previously ran `foreman-installer` in step 3B. + +
+ *No operating system selected.* +
+
+{% highlight bash %} +systemctl start httpd foreman.service foreman.socket +{% endhighlight %} +
+
+{% highlight bash %} +systemctl start apache foreman.service foreman.socket +{% endhighlight %} +
#### Common issues diff --git a/_includes/manuals/nightly/3.6_upgrade.md b/_includes/manuals/nightly/3.6_upgrade.md index 27ac5561f7..3464950be6 100644 --- a/_includes/manuals/nightly/3.6_upgrade.md +++ b/_includes/manuals/nightly/3.6_upgrade.md @@ -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. + + +To provide specific installation instructions, please select your operating system: + + #### Step 1 - Backup It is recommended that you backup your database and modifications to Foreman @@ -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. + +
+ No operating system selected. +
+
+{% highlight bash %} +systemctl stop httpd foreman.service foreman.socket +{% endhighlight %} +
+
+{% highlight bash %} +systemctl stop apache foreman.service foreman.socket +{% endhighlight %} +
+ +Now it's time to perform the actual upgrade. + +
+ No operating system selected. +
+ +
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 %} +
- yum upgrade tfm\* ruby\* foreman\* +
+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 %} +
-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. +
+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 }}`: + +
+{% highlight bash %} +deb http://deb.theforeman.org/ buster {{ page.version }} +deb http://deb.theforeman.org/ plugins {{ page.version }} +{% endhighlight %} +
+
+{% highlight bash %} +deb http://deb.theforeman.org/ bionic {{ page.version }} +deb http://deb.theforeman.org/ plugins {{ page.version }} +{% endhighlight %} +
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 %} +
#### 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 @@ -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 @@ -114,7 +187,7 @@ 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. @@ -122,33 +195,39 @@ 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 +
+ *No operating system selected.* +
+
+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 %} +
+
+This step is irrelevant for the chosen operating system. +
+ +##### Step 4 - Restart + +Start the application server. This is redundant if you previously ran `foreman-installer` in step 3B. + +
+ *No operating system selected.* +
+
+{% highlight bash %} +systemctl start httpd foreman.service foreman.socket +{% endhighlight %} +
+
+{% highlight bash %} +systemctl start apache foreman.service foreman.socket +{% endhighlight %} +
#### Common issues