orcharhino Upgrade Guide

This guide describes how to upgrade orcharhino to a newer version.

orcharhino is a large software suite undergoing active development. It is necessary to upgrade orcharhino when ATIX releases new versions to take advantage of its new features and bug fixes. Refer to the orcharhino Release Notes for more information.

ATIX provides guided upgrades performed by our consultants as part of our support subscriptions. Please contact us if you would like to make use of this service.

Make sure you carefully read all of the instructions, warnings, and recommendations presented in this guide and the appropriate version specific orcharhino Upgrade Notes in the ATIX Service Portal. ATIX does not offer support for recovery from a failed upgrade if you did not follow our upgrade guide.

Version Specific Instructions

Version specific upgrade instructions are published in the ATIX Service Portal. Log in with your ATIX Support login credentials and follow the link to the orcharhino Upgrade Notes. Make sure you carefully read the version specific instructions before starting the upgrade.

If you are skipping versions in a single upgrade, read all of the version specific instructions for all intermediary versions. For example, if you are upgrading from orcharhino 5.0 to 5.2, read both the instructions for the upgrade to version 5.1 and 5.2. Please contact us if you are unsure on how to start with your orcharhino upgrade.

Using Foreman Maintain

orcharhino upgrades are performed using the foreman-maintain utility. By default, foreman-maintain will interactively guide you through the upgrade process.

See the inbuilt documentation to modify this behaviour and for advanced options:

foreman-maintain --help
foreman-maintain upgrade --help
foreman-maintain upgrade run --help

Make sure there are no paused tasks before starting the upgrade.

Upgrade Steps

Always check the version specific upgrade steps before upgrading and always create a snapshot/backup as part of your upgrade.

  1. Check what orcharhino versions are available for upgrade

    1. Ensure foreman-maintain knows about the latest orcharhino releases

      yum update orcharhino-maintain-definitions
    2. List the available orcharhino releases

      foreman-maintain upgrade list-versions

      Refer to the orcharhino Release Notes for more information.

  2. Backup your orcharhino system

    We generally recommend running orcharhino as a virtual server and performing a system snapshot at this point. Refer to the backup mechanisms section for more information.

  3. Perform the upgrade itself

    foreman-maintain upgrade run --target-version <target_version>

    <target_version> must be one of the versions obtained from step 1b.

    Refer to using foreman maintain for more information.

    Setting the EXTERNAL_OR_SKIP_REPO_SETUP environment variable skips checking the repository setup and therefore allows you to run an orcharhino upgrade offline. The command from above can be expanded as follows:

    EXTERNAL_OR_SKIP_REPO_SETUP=1 foreman-maintain upgrade run --target-version 5.6

    Doing so, you must provide a way to access all packages normally found in repositories on the ACC via a local mirror.

  4. Verify that everything works

    Check the backend system status: Important system components are listed in the backend system status area of the about page. The info box lists each component with status OK.

You now have a new orcharhino version. Enjoy!

Once you have upgraded successfully, it may be useful to create another snapshot/backup. This will allow you to roll back to the state immediately after upgrading, saving you the need to repeat the upgrade if a roll back becomes necessary.

Upgrade Puppet

You can use foreman-maintain to upgrade Puppet.

Procedure
  1. Connect to your orcharhino using SSH:

    ssh root@orcharhino.example.com
  2. Run the Puppet upgrade check:

    foreman-maintain health check --label orcharhino-puppet-support

    foreman-maintain checks if your current Puppet version is supported on your orcharhino version. Then, it checks if there is an upgrade available. If yes, the upgrade can be performed automatically.

    Follow the instructions to either abort or start the upgrade process.

This check is also part of the orcharhino pre-upgrade checks.