Cluster setup using Minikube

• Prerequisites
• Step 1. Clone TBMQ repository
• Step 2. Installation
• Step 3. Running
• Step 4. Logs, delete statefulsets and services
• Upgrading
  • Backup and restore (Optional)
  • Upgrade to 2.1.0
    • Add Integration Executor microservice
    • Update third-party services
  • Run upgrade
• Next steps

This guide will help you to set up TBMQ in cluster mode using Minikube.

Prerequisites

You need to have a Kubernetes cluster, and the kubectl command-line tool must be configured to communicate with your cluster. If you don’t have Minikube installed, please follow these instructions. Additionally, you will need helm to be installed.

Step 1. Clone TBMQ repository

1
2
git clone -b release-2.1.0 https://github.com/thingsboard/tbmq.git
cd tbmq/k8s/minikube

Step 2. Installation

To install TBMQ execute the following command:

1
./k8s-install-tbmq.sh

Step 3. Running

Execute the following command to deploy TBMQ:

1
./k8s-deploy-tbmq.sh

After a while when all resources will be successfully started you can open http://{your-cluster-ip}:30001 in your browser (e.g. http://192.168.49.2:30001). You can check your cluster IP using command:

1
minikube ip

You should see TBMQ login page. Use the following default credentials for System Administrator:

Username:

1
[email protected]

Password:

1
sysadmin

On the first user log-in you will be asked to change the default password to the preferred one and then re-login using the new credentials.

Step 4. Logs, delete statefulsets and services

In case of any issues, you can examine service logs for errors. For example to see TBMQ node logs execute the following commands:

1) Get the list of the running tb-broker pods:

1
kubectl get pods -l app=tb-broker

2) Fetch logs of the tb-broker pod:

1
kubectl logs -f TB_BROKER_POD_NAME

Where:

• TB_BROKER_POD_NAME - tb-broker pod name obtained from the list of the running tb-broker pods.

Or use the next command to see the state of all the pods.

1
kubectl get pods

Use the next command to see the state of all the services.

1
kubectl get services

Use the next command to see the state of all the deployments.

1
kubectl get deployments

Use the next command to see the state of all the statefulsets.

1
kubectl get statefulsets

See kubectl Cheat Sheet command reference for more details.

Execute the following command to delete TBMQ nodes:

1
./k8s-delete-tbmq.sh

Execute the following command to delete all resources (including database):

1
./k8s-delete-all.sh

Upgrading

Review the release notes and upgrade instruction for detailed information on the latest changes.

If the documentation does not cover the specific upgrade instructions for your case, please contact us so we can provide further guidance.

Backup and restore (Optional)

While backing up your PostgreSQL database is highly recommended, it is optional before proceeding with the upgrade. For further guidance, follow the next instructions.

Upgrade to 2.1.0

TBMQ v2.1.0 introduces enhancements, including a new Integration Executor microservice and bumped versions for third-party services.

Add Integration Executor microservice

This release adds support for external integrations via the new Integration Executor microservice.

To retrieve the latest configuration files, including those for Integration Executors, pull the updates from the release branch. Follow the steps outlined in the run upgrade instructions up to the execution of the upgrade script (do not execute .sh commands yet).

Update third-party services

With v2.1.0, TBMQ updates the versions of key third-party dependencies, including Redis, PostgreSQL, and Kafka. You can review the changes by visiting the following link.

We recommend aligning your environment with the updated third-party versions to ensure full compatibility with this release. Alternatively, you may proceed without upgrading, but compatibility is only guaranteed with the recommended versions.

We do not provide step-by-step upgrade instructions for third-party services. For such procedures, please refer to the official documentation of the respective platform or, in the case of managed services, consult your service provider’s resources. Note: simply changing the image tag is not enough and may not be the correct or safe way to upgrade third-party services.

If you choose to skip updating third-party service versions, be sure to carefully check whether the merge process in the previous step has altered any of their versions. Revert those changes if necessary.

After addressing third-party service versions as needed, you can continue with the remaining steps of the upgrade process.

Run upgrade

In case you would like to upgrade, please pull the recent changes from the latest release branch:

1
git pull origin release-2.1.0

If you need to upgrade to a specific version, such as TBMQ v2.0.0, replace the release branch in the command above with the target branch name, e.g., release-2.0.0.

Note: Make sure custom changes of yours if available are not lost during the merge process.

If you encounter conflicts during the merge process that are not related to your changes, we recommend accepting all the new changes from the remote branch.

You could revert the merge process by executing the following:

1
git merge --abort

And repeat the merge by accepting theirs changes.

1
git pull origin release-2.1.0 -X theirs

There are several useful options for the default merge strategy:

• -X ours - this option forces conflicting hunks to be auto-resolved cleanly by favoring our version.
• -X theirs - this is the opposite of ours. See more details here.

After that, execute the following command:

1
./k8s-upgrade-tbmq.sh

1
./k8s-upgrade-tbmq.sh --fromVersion=FROM_VERSION

Note: You may optionally stop the TBMQ pods while you run the upgrade of the database with the below command.

1
./k8s-delete-tbmq.sh

This will cause downtime, but will make sure that the DB state will be consistent after the update. Most of the updates do not require the TBMQ to be stopped.

Once completed, execute deployment of the resources again. This will cause rollout restart of the TBMQ with the newest version.

1
./k8s-deploy-tbmq.sh

Next steps

• Getting started guide - This guide provide quick overview of TBMQ.

• Security guide - Learn how to enable authentication and authorization of MQTT clients.

• Configuration guide - Learn about TBMQ configuration files and parameters.

• MQTT client type guide - Learn about TBMQ client types.

• Integration with ThingsBoard - Learn about how to integrate TBMQ with ThingsBoard.