Upgrade to 5.5 [ LTS ]

This guide outlines the process for upgrading your ThingsHub installation to version 5.5.x. Upgrading to 5.5.latest is mandatory for all thingsHub systems with thingsHub 5.4 before upgrading to any later version. Likewise, upgrading directly to 5.5.x from unsupported versions should be avoided.

Following the Upgrade Path

For a seamless upgrade, consult the Upgrade thingsHub document to determine the exact sequence required for your current version. Look for "mandatory" in the page title to identify essential steps in the upgrade path. These mandatory upgrades ensure compatibility and prepare your system for the final upgrade to 5.5.x.

What's New?

Before upgrading, be sure to review the What's New page for details on new features and functionalities introduced in version 5.5.x. Additionally, the Breaking Changes page highlights any significant changes that might impact your existing setup.

Upgrading from Previous Versions

Direct upgrades are supported from version 5.3.x or 5.4.x to 5.5.x. If you're using an older version, upgrade to 5.3.x first (refer to the Upgrade to 5.3 document). This guide focuses solely on the incremental changes required from version 5.3.x.

Before You Begin

• Make sure to read the What’s New for the release 5.5.x.

• Checkout the Breaking Changes page to see if this version has any major breaking changes.

• Make sure the thingsHub Installation to be upgraded is at least in the version 5.3.x.

• Make sure the migration scripts have been run in the version 5.3.x.

• Make sure all the Prerequisites have been setup.

Prerequisites

This section lists all the new prerequisites that need to be setup before doing the upgrade.

• Notifier:
  Notifier is a cluster-level central service that provides an in-tenant notification service. From the version 5.4.x, Notifier is a mandatory service for both trackinghub and thingshub mode.

  Please refer to notifier installation guide to set it up in your kubernetes cluster.

• Map API keys
  Previously, Map API keys for thingsHub's map visualization were included by default. However, starting with version 5.5.x, these keys are now configurable through the tenant configuration for improved security and data isolation. This approach grants finer control and safeguards sensitive information within the thingsHub system.

  For more details and instructions on configuring your own API keys, please refer here.

Determine which version to upgrade to

This section shows how you can list all the available patch versions available for this thingsHub minor version i.e. 5.5. You can select the patch version you want to upgrade your thingsHub Installation to. We recommend using the latest available patch version to not miss out on any bug fixes and security patches.

!#/bin/bash
helm3 repo add smartmakers http://helm.smartmakers.de
helm3 repo update
helm3 search repo smartmakers/th-tenant --version 5.5 --versions

Update Tenant Configuration

This section outlines all the changes that you need to do and that are available in the tenant configuration file. These changes, however, only encompass incremental changes required from the oldest release you can upgrade from i.e. 5.3.x.

• Add the notifer block to the tenant configuration file:

  tenant_configuration.yaml

  YAML

  global
    name: thub_tenant
    tenant_mode: thingshub
    ...
    radar:
      enabled: false
    temporal:
      enabled: false
    ...
    notifier:
      enabled: true
      notifier_url: < kube-dns address to the notifier deployment in the same cluster >
      api_key: < `token` from the tenant credentials block in notifier config file >
    ...
  ...

  notifier_config.yaml

  CODE

  global:
    ...
    stream:
      prefix: notifier
    tenant_credentials: 
      thub_tenant:
        token: Randomly generated token to be put in `api_key` of the notifier block in tenant config
        api_key: API_Key_From_thub_tenant_Tenant
        comment: tenant credentials for thub_tenant

• Add Google Maps API keys, read more here Google Maps and other geo-service API Keys
  tenant_configuration.yaml

  CODE

  global
    name: thub_tenant
    tenant_mode: thingshub
    ...
    radar:
      enabled: false
    temporal:
      enabled: false
    ...
    notifier:
      ...
    ...
  
  iam:
    keys:
      map:
        key: AIzaSyAnMeQzzDcAVj3eHG4qCjNTzn85q5hjiC8
        id: fea2d474b8f48035
  ...

Backup Databases

Before applying the upgrade, back up all your data from both the time-series database and the relational database. This section explains how you can backup and restore you databases.

• Postgres

  CODE

  !#/bin/bash
  
  # backup:
  pg_dump -U <your-user> -h <address-to-your-db> -p <port> --database <your-database> --no-owner --format=t --verbose  >sql.dmp
  
  # restore:
  pg_restore -d <database> -h <address-to-your-db> -p <port> -U <your-user> --no-owner --role=<your-user> sql.dmp

   

• InfluxDB
  Make sure that influxdb is port-forwarded to port 8086 in the system where you’re running the shell commands.

  CODE

  !#/bin/bash
  # backup:
  influxd backup -portable -db things_hub ./influxdata/
  # restore:
  influxd restore -portable -db things_hub ./influxdata/

   

If you have setup any other backing-up mechanisms in your infrastructure, you can leverage that as well for the backups in place of the one mentioned above.

Apply the Upgrade

After setting up the everything, we can proceed to upgrade the thingsHub Installation.

!#/bin/bash
helm3 repo update
helm3 upgrade <your-thingshub-installation> --namespace <your-thingshub-namespace> smartmakers/th-tenant --version 5.1.8 -f <tenant_configuration.yaml> --atomic

Post Upgrade Steps

There are no explicit things, for this version, that you need to do after the upgrade of your thingsHub Installation. However, we recommend doing smoke testing on your thingsHub Installation after the upgrade to ensure that the system is functioning smoothly.
Based on your use-case, we recommend checking the functionality of incoming device data, integrations, dashboards and tracked assets' position update.