Upgrade Gateway Hub

Overview

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

Warning: Upgrades must be done sequentially from one minor version to the next, irrespective of patch version. For example, v1.1.0 can only be upgraded to v1.2.x.

These instructions apply to upgrading v1.1.0 onwards. If you want to upgrade v1.0.3 to 1.1.0, see Upgrade from 1.0.3 to 1.1.0.

The upgrade is performed from your installation machineThe installation machine is the machine that Gateway Hub is installed from. Files are copied from the installation machine on to the Gateway Hub nodes.. For prerequisites for the installation machine, see Installation machine requirements.

Upgrade Gateway Hub

Upgrading from one Gateway Hub version to the next version consists of the following steps:

  1. Download and unpack new Gateway Hub version
  2. Configure the JSON configuration file
  3. Perform the upgrade

Download and unpack new Gateway Hub version

Download and unpack the Gateway Hub binaries on to your installation machine:

  1. Download the Gateway Hub binaries for the version you are upgrading to from the ITRS group website:
    • The binaries packaged as a .tar.gz file named gateway-hub-1.x.x.tar.gz.
  2. Move the Gateway Hub.tar.gz file into the desired directory on your installation machine.
  3. Unpack the Gateway Hub binary using the command line.
    • This creates a folder called hub.

Configure the JSON configuration file

The upgrade requires a JSON configuration file.

You should already have a configuration file from when you installed Gateway Hub. If this file is no longer available, see instructions for creating a new one in Configure the JSON file.

Check that your JSON file has the correct connection and hosts information for your Gateway Hub nodes.

Note: If you specified custom install directories during the original installation process you cannot change these when upgrading.

Perform the upgrade

Make sure you have configured your JSON file with the correct information.

The upgrade only takes a few minutes and there is no disruption to data ingestion.

Note: Gateway Hub services are upgraded one node at a time. You may see requests to the REST API or Web Console fail if the request on the node being updated.

To upgrade Gateway Hub on a server, complete the following steps:

  1. Go to the folder called hub in your chosen directory.
    • This folder was created when you unpacked Gateway Hub.
  2. Run hubctl upgrade <JSON file>, replacing <JSON file> with the location of your JSON file.
  3. Wait for the upgrade to finish.

If successful, the PLAY RECAP output on the command line states a number of ok or changed configurations, and zero unreachable or failed, similar to the example below:

PLAY RECAP *****************************************************************
node1.example.itrs.com : ok=113  changed=62   unreachable=0    failed=0   
node2.example.itrs.com : ok=113  changed=62   unreachable=0    failed=0   
node3.example.itrs.com : ok=171  changed=94   unreachable=0    failed=0   
localhost                  : ok=1    changed=0    unreachable=0    failed=0