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.
Ensure 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 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. Ensure 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.
orcharhino upgrades are performed using the
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
Ensure there are no paused tasks before starting the upgrade.
orcharhino server and orcharhino proxies only require repositories provided by ATIX. They contain all packages required to install, upgrade, and run orcharhino and orcharhino Proxies, including the base operating system repositories. ATIX does not support using additional custom repositories on your orcharhino or orcharhino Proxies.
Check what orcharhino versions are available for upgrade
foreman-maintainknows about the latest orcharhino releases
# yum update orcharhino-maintain-definitions
List the available orcharhino releases
# foreman-maintain upgrade list-versions
Refer to the orcharhino Release Notes for more information.
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.
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.
EXTERNAL_OR_SKIP_REPO_SETUPenvironment 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.
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.
You can use
foreman-maintain to upgrade Puppet.
Connect to your orcharhino using SSH:
# ssh firstname.lastname@example.org
Run the Puppet upgrade check:
# foreman-maintain health check --label orcharhino-puppet-support
foreman-maintainchecks 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.