Upgrade thingsHub

Terminologies:

• Upgrade Path: A defined order for upgrading to the desired version. This path may involve multiple intermediate steps.

• Mandatory Versions: Specific versions within the upgrade path that are required for successful installation of the target version. These versions will be clearly identified as "(mandatory)" for your reference.

Introduction

We recommend that you upgrade thingsHub often to stay current with the latest fixes and enhancements. You can upgrade to any of the supported releases from any supported release.

Because thingsHub upgrades are backward compatible, the upgrade process is mostly straightforward, and existing devices, data tables, integration or dashboard will not change.

There are, however some versions that are must in the upgrade path. You should not upgrade to any later versions before upgrading to these compulsory versions. These must-upgrade versions are marked as (mandatory) in the Page title.

Following the Upgrade Path

Upgrade path is the mandatory steps that your thingsHub system must go through before upgrading to the desired version.
It is critical to adhere to the designated upgrade path, particularly regarding mandatory versions. Skipping these intermediate steps can lead to:

• Compatibility Issues: Newer versions may not function correctly with older, unsupported versions.

• Software Bugs: Bugs or unintended behavior may arise due to missing functionalities from skipped versions.

• System Instability: In the worst-case scenario, skipping mandatory versions could render your system unstable or inoperable.

Computing the Upgrade Path

Upgrade path from version A to version B will include all the mandatory versions between versions A and B, followed by the version B at the end.

For example: To upgrade from 5.1 to 5.4, the upgrade path will look like:
5.1 → 5.3 → 5.4

To learn what’s available in a thingsHub release, refer to What’s New page.

Upgrade Failure and Rollback

This section outlines potential issues that may arise during the upgrade process and guides how to handle them. It serves as a reference for both customers and support teams to ensure a smooth and successful upgrade.

Essential: Backup the databases before the upgrade

Before going through the upgrade, please make sure to do a complete backup of the databases; postgres and influx. These will be crucial in handling in case the deployment goes into an irrecoverable state.

Pre-Upgrade Migration Failure

While it's unlikely to encounter issues during the pre-upgrade steps, if they do arise, please contact our customer support portal for assistance.

Upgrade Failure

1. Helm Errors:

   • Identify the cause: Carefully review the error message to understand the underlying issue.

   • Consult documentation: Refer to the Smart-makers documentation or our support resources for troubleshooting guidance.

   • Contact support: If you're unable to resolve the issue, reach out to our customer support team for further assistance.

2. Unsuccessful Upgrades and Services Not Coming Up:

   • Verify database consistency: Ensure that the database has remained consistent.

   • Rollback to the previous version: If the database is consistent, use the helm rollback command to revert the tenant to the previous version.

     CODE

     helm history {release} -n {namespace} ## get the list of revisions
     helm rollback {release} {revision}

   • Retry upgrade: Once the rollback is successful, attempt the upgrade again, carefully reviewing any configuration changes that may have caused the initial failure.

Post-Upgrade Migration Failure

1. Legacy Alert and Notification Channel Migration Failure ( For Thingshub 6 ):

   • Update Grafana query: If the legacy alert migration fails in Grafana UI, manually update the alert rule or notification channels to ensure the alert functions correctly. Refer to the migration guide for detailed instructions.

   • Recreate alert: As a last resort, if updating the query doesn't resolve the issue, consider deleting and recreating the alert.

Any-other Issues

• Contact support: For any other issues encountered during the upgrade, please reach out to our customer support portal for assistance.

Additional Considerations

• Regular backups: Maintain regular backups of your system to ensure a safe and efficient rollback process if necessary.

• Testing and validation: Thoroughly test and validate the upgraded system to identify any issues with your use case.

Upgrading to specific thingsHub Version

Refer to any of the following upgrade guides: