Upgrade to 5.0 ( Mandatory )

This guide outlines the process for upgrading your ThingsHub installation to version 5.0

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.0.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.0.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 4.14.15 to 5.0.x. If you're using an older version, upgrade to 4.14.15 first. This guide focuses solely on the incremental changes required from version 4.14.15.

Before You Begin

• Make sure to read the What’s New for the release 5.0.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 in the version 4.14.15.

• 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.

• Tenant Mode:
  With thingsHub 5, two modes of deployment were introduced:

  • thingsHub mode: Deploying in thingshub mode does not require any external dependencies, and the dependencies do not need to be mentioned in the tenant configuration. A minimal example of the tenant configuration file for thingshub mode deployment is given in Tenant Configuration.

  • trackinghub mode: Deploying in trackinghub mode will require several external dependencies to be set up to work with thingsHub.

• HA-NATS
  thingsHub 5 introduced a clusterwide Highly Available NATS service for passing message within and between services in the thingsHub system. On Premise customers will have to deploy this service on their premise separately.
  
  Instructions for installing the highly available NATS broker are available in the thingsHub documentation: https://docs.smartmakers.io/thingshub4/highly-available-nats

• Backup-Cron
  thingsHub 5 also introduces a backup cron job where the database and influxDB is periodically backed up.

For further details on the differences between the thingshub and the trackinghub mode, please contact our sales team.

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.0. 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.0 --versions

thingsHub 5.0+ also has an enhanced tracking mode with enhanced tracking features. For more details on enhanced tracking, and upgrading thingsHub with enhanced tracking features, please contact our sales team.
This document assumes that thingshub is being set up with thingshub or trackinghub mode without enhanced tracking features.

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.0.x.

• Add the radar and temporal blocks and set them to false:

  tenant_configuration.yaml

  CODE

  global:
    ...
    ...
    radar:
      enabled: false
    temporal:
      enabled: false
    ...
    ...
  ...

• Add HA-NATS configuration
  tenant_configuration.yaml

  CODE

  global:
    ...
    ...
    nats:
      nats_url: nats://nats-svc.thub.svc.cluster.local:4222
      is_cluster_wide: true
      user: NATS_USERNAME
      password: NATS_PASSWORD
    ...
  ...

• Add Backup Cron Job configuration to the tenant configuration
  tenant_configuration.yaml

  CODE

  global:
    ...
    ...
  ...
  
  backup-cron:
    enabled: true
  ...

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.0.16 -f <tenant_configuration.yaml> --atomic

Post Upgrade Steps

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.

Notes