Release compatibility and migration guide
For most releases, migration can happen without requiring major changes. However, sometimes, manual changes cannot be fully avoided for system operators or users of the REST API. In these cases, the following guide lists all required manual steps for upgrading a tenant or its users from an earlier to a later release.
Release compatibility
Dependencies compatibility
The following table illustrates the compatibility of the last few thingsHub releases with its base dependencies, i.e. Kubernetes, PostgreSQL and InfluxDB.
4.0 | 4.1 | 4.2 | 4.3 | 4.13.x | 4.14.x | 5.0.x | 5.1.x | 5.2.x | 5.3.x | |
---|---|---|---|---|---|---|---|---|---|---|
Kubernetes | ≥1.12 & ≤1.17 | ≥1.15 & ≤1.18 | ≥1.12 & ≤1.18 | ≥1.12 & ≤1.18 | =1.23 | ≥1.23 & ≤1.25 | ≥1.24 & ≤1.25 | ≥1.24 & ≤1.25 | ≥1.24 & ≤1.25 | ≥1.24 & ≤1.27 |
PostgreSQL | ≥9.6 & ≤11.11 (≠10.10) | ≥9.6 & ≤11.11 (≠10.10) | ≥9.6 & ≤11.11 (≠10.10) | ≥9.6 & ≤11.11 (≠10.10) | ≥9.6 & ≤11.11 (≠10.10) | ≥9.6 & ≤11.11 (≠10.10) | ≥9.6 & ≤11.11 (≠10.10) | ≥9.6 & ≤11.11 (≠10.10) | ≥9.6, ≤11.11 & ≤16.1.0*(≠10.10) | ≥9.6, ≤11.11, ≤16.1.0* (≠10.10) |
InfluxDB | ≥1.7 && ≤1.8 | ≥1.7 && ≤1.8 | ≥1.7 && ≤1.8 | ≥1.7 && ≤1.8 | ≥1.7 && ≤1.8 | ≥1.7 && ≤1.8 | =1.8 | =1.8 | =1.8 | =1.8 |
Note that version 10.10 of PostgreSQL contains a regression that is not compatible with Grafana, so this version is explicitly not compatible with the thingsHub.
*PostgreSQL v16.1.0 : thingsHub 5 is working with the latest Postgres v16 release. However, Postgres ≥11.11 is still being tested for long term compatibility.
We recommend using Postgres ≥9.6, ≤11.11 (≠10.10) for now.
HA NATS Compatibility (for thingsHub ≥ 5)
thingsHub 5+ uses the highly available message broker NATS. thingsHub is compatible with the following version of NATS:
NATS version: v2.6.5
NATS Helm chart version: helm.sh/nats-0.11.0
Network server compatibility≥1.23 & ≤1.27
The following table shows which thingsHub release is tested with which release of the network servers.
4.0 | 4.1 | 4.2 | 4.3 | 4.x | 5.x | |
---|---|---|---|---|---|---|
Kerlink SPN | =2.3 | =2.3 | =2.3 | =2.3 | =2.3 | =2.3 |
Kerlink WMC3 | ≥3.0 & ≤3.2 | ≥3.0 & ≤3.2 | ≥3.0 & ≤3.2 | ≥3.0 & ≤3.2 | ≥3.0 & ≤3.2 | ≥3.0 & ≤3.2 |
Loriot | ≥4.0 & ≤6.0 | ≥4.0 & ≤6.0 | ≥4.0 & ≤6.0 | ≥4.0 & ≤6.0 | ≥4.0 & ≤6.0 | ≥4.0 & ≤6.0 |
MZ Connect | * | * | * | * | * | * |
Sigfox | * | * | * | * | * | * |
Swisscom LPN | * | * | * | * | * | * |
The Things Industries | * | * | * | * | * | * |
The Things Network | 2 | 2 | 2 | 2 | 2 | 2 |
For the network servers marked with *, there is insufficient information provided by the network operator to state release compatibility.
3rd-party system compatibility
This table shows which release of the thingsHub is compatible with which 3rd party system, e.g.
4.0 | 4.1 | 4.2 | 4.3 | 4.x | 5.x | |
---|---|---|---|---|---|---|
Cumulocity | ≥10.4 & ≤ 10.6 | ≥10.4 & ≤10.6 | ≥10.4 & ≤10.6 | ≥10.4 & ≤10.6 | ≥10.4 & ≤10.6 | ≥10.4 & ≤10.6 |
David | ≥1.7 & ≤1.8 | ≥1.7 & ≤1.8 | ≥1.7 & ≤1.8 | ≥1.7 & ≤1.8 | ≥1.7 & ≤1.8 | ≥1.7 & ≤1.8 |
MQTT | =5.0 & =3.1 & =3.1.1 | =5.0 & =3.1 & =3.1.1 | =5.0 & =3.1 & =3.1.1 | =5.0 & =3.1 & =3.1.1 | =5.0 & =3.1 & =3.1.1 | =5.0 & =3.1 & =3.1.1 |
MySQL | =8.0 | =8.0 | =8.0 | =8.0 | =8.0 | =8.0 |
Migrating to newer releases
Migrating from release 4.x to thingsHub 5
thingsHub modes
With thingsHub 5, two modes of deployment were introduced:
thingsHub mode
Deploying inthingshub
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 intrackinghub
mode will require several external dependencies to be set up to work with thingsHub. Please contact the sales team for further details on setting uptrackinghub
mode.
User Action:
Add the field
tenant_mode
in the tenant configuration file and make sure it is set to the appropriate value as shown in the example config file: Tenant configuration
Data Table Migration
The legacy data tables in thingsHub have now been deprecated, and extended data tables have been introduced.
Extended Datatables support more functionalities and allow data push to Exchange Datatables.
Corresponding migration has to be done for these data tables before upgrading to thingsHub 5.
User Action:
The data table migration tool for legacy data tables is available to the operator as a part of thubctl.
Please contact the smartmakers team for detailed instructions on how to migrate the data tables.
Configure HA NATS
ThingsHub 5 uses HA NATS, which may be internal NATS or External NATS.
Internal NATS is deprecated due to Architectural constraints and we plan to remove this support completely in the future. The preferred way of using NATS in thingsHub is external NATS
User Action
Configure HA NATS for individual tenant and change the tenant configuration file to include these changes. The steps for doing this have been documented in detail in thingsHub Highly Available Message Broker (NATS)
Migrating from release 3.x to 4.x
Establish suitable permissions for all users
Required actions
Release 4.0 introduced a role-based permission system. This means users can now have different sets of permissions depending on their role in the project or company. With these new roles it is necessary to make a decision which role each user should have. By default, for maximum security, no user will have a role assigned at all (except for the admin user, which has all permissions). As a consequence, the admin user will have to assign the most fitting role to each user after the system was upgraded. The new role “Tenant Owner” is closest to what users had before.
Migrating from release 3.8 to 3.9
Simplified labels for devices by removing the key and keeping only value
Usage Example
Before this change, device labels were key value pairs. Every key could be assigned once per device:
{
{
"id": "manufacturer:nke",
"key": "manufacturer",
"value": "nke"
},
{
"id": "measurement:temperature",
"key": "measurement",
"value": "temperature"
},
{
"id": "location:office",
"key": "location",
"value": "office"
}
}
With version 3.8 and later, labels are simple strings, more akin to tags:
{
"nke",
"temperature",
"office"
}
Migration of existing data
Existing labels are migrated to the new schema by concatenating key and value with an underscore:
Required actions
Consumers of the REST-API need to adapt their data model as described above.
Queries to the REST API which use query parameters to filter by device labels need to be adapted to use the new style of labels.
Added endpoints for easily creating/updating/deleting labels on a device
Usage example
Up to version 3.7, labels were managed using the API endpoint for the device which they label:
PUT /api/v3/devices/:device-id
{
"labels": [
{
"key": "X",
"value": "Y"
},
{
"key": "A",
"value": "B"
]
}
Starting with version 3.8, labels are managed with dedicated endpoints using the CRUD pattern. E.g. labels are created with the verb POST to the resource /api/v3/device/:id/labels:
POST /api/v3/devices/:device-id/labels?labels=foo,bar
Retrieving labels
GET /api/v3/devices/:device-id/labels
Deleting a label:
DELETE /api/v3/devices/:device-id/labels/:label-id
Data migration
Not applicable.
Required actions
Consumers of the REST API need to be migrated to the new interface.
Added selectors for integrations that will match devices labels
Previously, device selection happened by an integration's label.
{
"labels": [
{
"key": "foo",
"value": "bar"
},
{
"key": "myxl",
"value": "plyx"
}
],
...
}
From 3.6 on device selection happens by dedicated selectors.
As of now, only logical disjunction (with $or
is supported).
{
"selectors": {
"$or": [
"foo_bar",
"myxl_plyx",
]
},
...
}
Data migration
Not applicable.
Required actions
Consumers of the REST API need to be migrated to the new interface.
Disabled public endpoints for device information and device activation
To the best of our knowledge, this API has not been in use.
Required actions
Adapt consumers of the REST API to manually create devices.
Migrating from release 3.7 to 3.8
Device ID are now unique strings instead of integers
Valid IDs have a maximum length of 63 characters and may contain alphanumeric characters and dashes.
Before 3.6, devices used numerical IDs.
{
"id": 4,
...
}
Starting with 3.7, devices use strings as IDs.
{
"id": "device-4",
...
}
Data migration
Existing devices IDs are converted to IDs of the pattern
device-<int>
, e.g. the numeric ID4
of a device is transformed to the stringdevice-4
.Device created through auto-activation will get an ID of the pattern
<network-server-id>-<network-device-id>-<unique-int>
, where the network server ID is the thingsHub's ID of the network server and the network device ID is the network server's device ID. A unique integer is appended to ensure collision cannot happen.
Required actions
Consumers of the REST API need to be migrated to the new interface.
User-created Queries to the time series database, e.g in the visualizer, which reference devices by ID need to be modified to use the new device ID schema.
Disabled public endpoints for device information and device activation
To the best of our knowledge, this API has not been in use.
Required actions
Adapt consumers of the REST API to manually create devices.