Upgrading orcharhino Server

This guide describes how you can upgrade orcharhino to a newer version. See the orcharhino Release Notes for a high level overview of available versions and their features.

As part of the optional service Assisted Update Support, ATIX AG provides guided upgrades together with the Support team. Please contact us if you would like to make use of this service.

Ensure that 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 AG does not offer support for recovery from a failed upgrade if you did not follow our upgrade guide.

ATIX AG does not support using third party repositories on your orcharhino Server or orcharhino Proxy Servers. Resolving package conflicts or other issues due to third party or custom repositories is not part of your orcharhino support subscription. Please contact us if you have any questions.

Performing the upgrade

Use this procedure to upgrade orcharhino Server from orcharhino 7.5 to orcharhino 7.6.

Procedure

  1. Check the version specific upgrade steps for orcharhino 7.6 in orcharhino Upgrade Notes in the ATIX Service Portal.

  2. Backup your orcharhino Server:

    ATIX AG recommends running orcharhino Server as a virtual machine and performing a system snapshot at this point. For more information, see Backing Up orcharhino.

  3. Update and list the versions known to your orcharhino Server:

    $ dnf upgrade orcharhino-maintain-definitions
$ orcharhino-maintain upgrade list-versions

  4. Upgrade your orcharhino Server:

    $ orcharhino-maintain upgrade run --target-version 7.6

  5. Ensure that all components report their status as ok:

    $ hammer ping

Upgrading Puppet

orcharhino supports Puppet 7 and 8. After upgrading your orcharhino Server to 7.6, you can upgrade from Puppet 7 to Puppet 8 or from Puppet 7 or Puppet 8 to OpenVox 8.

When upgrading Puppet from version 7 to 8, the Ruby version shipped in Puppet changes. This affects only Puppet’s own Ruby and does not alter the Ruby used by orcharhino or your operating system. Any extra Ruby gems you have added to the Puppet Ruby environment will be removed, including r10k. You must reinstall them after the upgrade.

You can use orcharhino-maintain to upgrade Puppet. Upgrading Puppet on orcharhino is independent of the orcharhino upgrade process and does not happen automatically.

Procedure

  1. On your orcharhino Server, run the Puppet upgrade check:

    $ /opt/orcharhino/maintain/repo_map/upgrade_puppet.py --show-available-versions

    Note down the available Puppet version. Versions with a openvox suffix indicate OpenVox as Puppet replacement.

  2. Upgrade Puppet:

    $ /opt/orcharhino/maintain/repo_map/upgrade_puppet.py --update-puppet -v 8

Migrating to OpenVox

You can migrate from Puppet to OpenVox. This procedure will upgrade Puppet 7 or Puppet 8 on your orcharhino Server to OpenVox 8.

Procedure

  • On your orcharhino Server, migrate to OpenVox:

    $ /opt/orcharhino/maintain/repo_map/upgrade_puppet.py --update-puppet

Troubleshooting permission issues

orcharhino upgrades perform pre-upgrade checks. If the pre-upgrade check discovers permission issues, it fails with an error similar to the following one:

2024-01-29T20:50:09 [W|app|] Could not create role 'Ansible Roles Manager': ERF73-0602 [Foreman::PermissionMissingException]: some permissions were not found:

If you see an error like this on your orcharhino Server, identify and remedy the permission issues.

Procedure

  1. On your orcharhino Server, identify permission issues:

    $ orcharhino-maintain health check --label duplicate_permissions

  2. Fix permission issues:

    $ foreman-rake db:seed
Verification

  • Rerun the check to ensure no permission issues remain:

    $ orcharhino-maintain health check --label duplicate_permissions