Upgrade Gateway Hub

Overview

This document guides you through how to upgrade Gateway Hub from one version to the next.

These instructions cover v2.2.x and later.

In general, upgrades cannot be performed in the following circumstances:

Upgrades from any previous version to a 2.2.x version.
Upgrades between 2.2.x point releases.

Warning: When upgrading, data in Gateway Hub is transformed to be compatible with the latest version. Existing data is not preserved. If you may need to downgrade in the future, you must manually create a backup before upgrading.

Prerequisites

To perform an upgrade, the following are required:

Installation machine, which must fulfil the Installation machine requirements. This does not have to be the machine used during the original installation of Gateway Hub.
The installation machine must be able to reach all nodes in the current Gateway Hub installation. However, Gateway Hub does not have to be running.
The same version of Gateway Hub must be installed on all nodes.
A valid installation configuration file.

Upgrade

Before upgrading your Gateway Hub make sure it is in a healthy state. To do this, check the Gateway Hub self monitoring metrics, and resolve any problems.

Beginning Gateway Hub 2.2.x, you can perform an upgrade by performing the following steps:

Download the latest Gateway Hub binaries from ITRS Downloads to your installation machine.
- The binaries are packaged as a .tar.gz file named hub-installer-<version>.tar.gz.
Move the Gateway Hub.tar.gz file into a user writeable directory.
Unpack the Gateway Hub binary using the command line.
- This creates a folder called hub-installer-<version>.
Run the hubctl setup upgrade <config_file> command from your installation machine.

When upgrading you can also perform reconfiguration, including options available only in the latest version. However, protected settings cannot be changed.

For more information about available commands, see hubctl tool.

Downgrades

When you perform an upgrade Gateway Hub preserves the full directory structure of the existing installation and creates a new structure for the latest version. You may manually delete the previous directory structure once the upgrade is complete, or you may prefer to keep it either for reference or in order to be able to restore your Gateway Hub to its previous state if you decide to revert to the previous version later.

Recall that, when upgrading, data in Gateway Hub is transformed to be compatible with the latest version. Existing data is not preserved so you must manually create a backup before upgrading. This is recommended if you might downgrade in the future.

If you later downgrade your Gateway Hub you can use a backup to restore your pre-upgrade data only.