Upgrade Guide

orcharhino is a large software suite, with multiple components undergoing active development. To take advantage of new features as well as bug fixes, it is necessary to upgrade orcharhino when new versions are made available by ATIX.

This guide exists to describe the steps that are needed to upgrade orcharhino.

Note

ATIX sells upgrades (performed by our consultants) as part of it’s optional support package. If you would like to make use of this service, instead of upgrading orcharhino yourself, please feel free to contact us. (See also: Contact).

The upgrade guide contains the following subsections:

Notes and Background

orcharhino is normally shipped as part of a specific CentOS version maintained by ATIX. As such, upgrades to the CentOS host orcharhino is running on happen as part of the orcharhino upgrade as detailed in this guide. This ensures orcharhino will run in the same environment it was built for and tested in.

Important

It is highly recommended to create a system snapshot prior to upgrading orcharhino! This will allow you to roll back if anything goes wrong.

Upgrade Steps

Note

To upgrade orcharhino we require root access on the host orcharhino is running on.

We perform the following steps to upgrade orcharhino (commands are run as root, on the host orcharhino is running on):

  1. Perform pre-upgrade checks.

    1. Check that there are no running tasks (which might be interrupted by the upgrade):

      foreman-rake katello:upgrade_check
      
    2. Stop all orcharhino services, to ensure no new tasks will be started:

      katello-service stop
      
  2. (optional, recommended) Create a snapshot of the orcharhino system.

    Note

    This step is highly dependent on where and how you are running orcharhino, and cannot be documented here with a one size fits all approach.

  3. Perform the upgrade.

    1. Upgrade the packages (both of orcharhino and the CentOS it runs on):

      yum update
      
    2. Upgrade orcharhino components:

      foreman-installer --upgrade
      

    Warning

    Upgrading the orcharhino packages (yum update or yum update orcharhino) without running foreman-installer --upgrade can leave orcharhino in an inconsistent state. Please make sure you always either perform all of the upgrade steps, or roll back your system to a state from before the start of the upgrade process.

    In general, you should never run yum update on the orcharhino host, unless you are planning to perform all the steps from this guide. If you know what you are doing, and you want to upgrade some package without upgrading orcharhino, run yum update <package_name> to explicitly upgrade just that package.

  4. Check that everything works!

    Note

    The foreman-installer will restart orcharhino after the upgrade. Some orcharhino components (like foreman_proxy) may take 1-2 Minutes until they are back online. Please be patient before concluding the upgrade failed.

    1. Check whether all services have restarted:

      katello-status
      
    2. Check the backend system status:

      Important system components are listed under Administer > About > Backend System Status in the web interface. (See also: About). The Backend System Status info box should list the status as “OK” for all components.

    3. Check that important background tasks are running:

      The Tasks “Listen on Candlepin events” and “Monitor Event Queue” should always have a running instance. (See Background Tasks for details).

You now have a new orcharhino version. Enjoy!

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

Important

Newer snapshots will include lots of back references to older snapshots. This can be inefficient if too many snapshots are kept at the same time. It is recommended to limit the number of snapshots to no more than three per host. Consider deleting older snapshots when creating new ones.