Upgrade Gateway Hub

Overview Copied

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

Newer releases of Gateway Hub bring additional functionality, critical bug fixes, and performance improvements. Therefore, it is extremely important to keep Gateway Hub up to date.

These instructions cover v2.2.x and later.

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

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 Copied

To perform an upgrade, the following are required:

Upgrade Copied

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.

Gateway Hub upgrade Copied

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

  1. 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.
  2. Move the Gateway Hub.tar.gz file into a user writeable directory.
  3. Unpack the Gateway Hub binary using the command line.
    • This creates a folder called hub-installer-<version>.
  4. Run the hubctl setup upgrade <install_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.

Gateway upgrade Copied

If you are using Gateway and Active Console to view Gateway Hub self-monitoring metrics, ensure you are using the latest available include file when upgrading Gateway Hub. This is because Gateway Hub upgrades may include changes to the Collection Agent plugins being used to monitor your Gateway. For example, when upgrading from Gateway Hub version 2.3.x to version 2.4.x, the linux-infra plugin is replaced with the system plugin.

For the latest information about configuring self monitoring, see Gateway Hub integration.

Operating system upgrade Copied

To update the host operating system of your Gateway Hub cluster, perform the following steps on each node:

  1. Stop Gateway Hub on this node:

    hubctl stop <config_file>

  2. Update the operating system following your distributions standard procedure.

  3. Start Gateway Hub on this node:

    hubctl start <config_file>

If the Gateway Hub orchestration service has been registered with systemd, you will need to mask the orchestration service when upgrading the operating system on each node. For more information, see Registration with systemd.

Downgrades Copied

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.

Common issues Copied

This section provides additional guidance for common issues encountered when performing an upgrade.

Registration with systemd Copied

If the Gateway Hub orchestration service has been registered with systemd, you will need to mask the orchestration service when upgrading Gateway Hub or the clusters operating system.

For more information about registration with systemd, see Registration with systemd in Install.

To mask the orchestration service when upgrading:

  1. Mask and stop the orchestration service by running the following on each node:

    sudo systemctl mask hub-orchestration
sudo systemctl stop hub-orchestration

  2. Perform the Gateway Hub upgrade or Operating system upgrade steps.

  3. Unmask and restart the orchestration service by running the following on each node:

    sudo systemctl unmask hub-orchestration
sudo systemctl start hub-orchestration
["Geneos"] ["Geneos > Gateway Hub"] ["User Guide"]

Was this topic helpful?