Upgrade to 6.0 [ Mandatory ]

This guide outlines the process for upgrading your ThingsHub installation to version 6.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 6.0.x.

What's New?

Before upgrading, be sure to do the following:

Review the What's New page for details on new features and functionalities introduced in version 6.0.x. Additionally, the Breaking Changes page highlights any significant changes that might impact your existing setup.

The Pre Upgrade Migration & Post Upgrade Migration will guide you through the essential migrations that need to be done before and after the upgrade to thingsHub 6.

Upgrading from Previous Versions

Direct upgrades to thingsHub 6.0 can be done if you are using any thingsHub version 5.3.latest+.

If you're using an older version, an upgrade to version 5.3.latest or 5.5.latest is recommended before you upgrade to thingsHub 6.0.x.

Before You Begin

Make sure to read the What’s New for the release 6.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 5.3.latest+.
Make sure all the Prerequisites have been setup.
Make sure you go thoroughly through the mentioned Migration Guides. These are mandatory.

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. Please ensure Notifier is installed.
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. Please ensure Map API keys are available and properly set up in the tenants.

Determine which version to upgrade to

This section shows how you can list all the available patch versions available for this thingsHub version i.e. 6.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.

BASH

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

Pre Upgrade Migration

ThingsHub operators upgrading to thingsHub 6.0.x using the Data Table Out node on thingsflow must complete a pre-upgrade migration to ensure the node works properly. Please consult the following migration guide for the necessary steps in doing this migration:Migration Guide: Transitioning to new Data Table Out Node

Update Tenant Configuration

This section outlines all the changes that you need to make 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 notifier 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

YAML

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

Update kafka-node-configuration in the thingsflow block
The kafka node configuration in the thingsflow block included within the global from thingsHub version 5.3.x has been updated to improve the usability and readability.

If you had disabled the kafka node, you can just delete the block from the global section and proceed with the upgrade.
old_tenant_configuration.yaml

YAML

global
  name: thub_tenant
  tenant_mode: thingshub
  ...
  
  thingsflow:
  enabled: true
  node_config:
    kafka:
      enabled: false
  ...
iam:
  ...
...

new_tenant_configuration.yaml

YAML

global
  name: thub_tenant
  tenant_mode: thingshub
  ...
  
iam:
  ...
...

If you were actively using the kafka-tls node and its configuration, you’ll need to update the kafka configuration block
old_tenant_configuration.yaml

YAML

global
  name: thub_tenant
  tenant_mode: thingshub
  ...
  
  thingsflow:
  enabled: true
  node_config:
    kafka:
      enabled: true
        ca_cert: <your ca cert>
        tls_cert: <your client cert>
        tls_key: <your client key>
  ...
  
iam:
  ...
...

new_tenant_configuration.yaml

CODE

global
  name: thub_tenant
  tenant_mode: thingshub
  ...
  
iam:
  ...

thingsflow:
  enabled: true

  kafka_tls_config:
    ca_cert: <your ca cert>
    tls_cert: <your client cert>
    tls_key: <your client key>
...

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

YAML

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 your databases.

Postgres

BASH

!#/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.

BASH

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

If you have set up 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 everything, we can proceed to upgrade the thingsHub Installation.

BASH

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

Post Upgrade Steps

Necessary Migrations

Operators must complete the following necessary migrations as post-upgrade steps to ensure that their thingsHub installation is working properly. Three of these migrations need to be completed after the upgrade to thingshub 6.0.x. The migrations, along with their corresponding migration guide documents are as follows:

Legacy Grafana Alerts to Unified Grafana Alerts Migration: Migration Guide: Legacy Alerts to Unified Alerting in Visualizer (Grafana)
Grafana Deprecated Angular Plugin Migration: Breaking Changes in thingsHub 6.0 | Breaking-Changes-from-Visualizer-Upgrade-to-Grafana-10.4
Legacy Data Table to Extended Data Table Migration: Migration Guide: Transitioning from Legacy Data Tables to Extended Data Tables
Tenants Upgrading from Thingshub 5.3.x should ensure that the “Data Table In” node in thingsflow is working as expected. The data format has changed since 5.3.x. The flows should be updated to ensure they work smoothly: Migration Guide: Transitioning to new Data Table In Node

Post Upgrade Testing

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