Minikube

This guide covers setting up TBMQ in cluster mode using Minikube.

• A running Kubernetes cluster with kubectl configured to communicate with it. If you don’t have Minikube installed, follow these instructions.

git clone -b release-2.3.0 https://github.com/thingsboard/tbmq-pe-k8s.git
cd tbmq-pe-k8s/minikube

Run the installation script:

./k8s-install-tbmq.sh

Before proceeding, ensure you have an active TBMQ license. If you don't have one yet, visit the Pricing page, choose a pay-as-you-go subscription or a perpetual license, and use the calculator to size your deployment — session and throughput limits, production and development instances, and any add-ons — to obtain your license key.

Create a Kubernetes secret with your license key:

export TBMQ_LICENSE_KEY=YOUR_LICENSE_KEY_HERE
kubectl create -n thingsboard-mqtt-broker secret generic tbmq-license --from-literal=license-key=$TBMQ_LICENSE_KEY

Deploy TBMQ:

./k8s-deploy-tbmq.sh

Once all resources have started, open http://{your-cluster-ip}:30001 in your browser (e.g. http://192.168.49.2:30001). Check your cluster IP with:

minikube ip

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

Username:

[email protected]

Password:

sysadmin

On first login, you are prompted to change the default password and re-login with the new credentials.

To view TBMQ node logs:

1. List running TBMQ pods:

   kubectl get pods -l app=tbmq

2. Fetch logs for a specific pod:

   kubectl logs -f TBMQ_POD_NAME

   Where TBMQ_POD_NAME is the pod name from the list above.

To check the state of all pods, services, deployments, and statefulsets:

kubectl get pods
kubectl get services
kubectl get deployments
kubectl get statefulsets

See the kubectl Cheat Sheet for more details.

To delete TBMQ nodes:

./k8s-delete-tbmq.sh

To delete all resources including databases:

./k8s-delete-all.sh

1. Check the version-specific notes below for any preparation your target version requires.
2. Back up your database (optional but recommended).
3. Run the upgrade commands.

For full version history and supported upgrade paths, see the upgrade instructions page. If the documentation does not cover your specific upgrade path, contact us for guidance.

If there are no version-specific notes for your upgrade path, skip directly to Run upgrade.

Backing up your PostgreSQL database before upgrading is highly recommended but optional. For guidance, follow the backup and restore instructions.

This is a standard upgrade from v2.2.0. No third-party component changes are required — the official images are already in use since v2.2.0.

Proceed with the upgrade.

CE-to-PE migration is supported for the same version only. If you are on an earlier CE version, upgrade TBMQ CE to the latest version first. For all supported paths, see the upgrade instructions.

Before upgrading, merge your current configuration with the latest TBMQ PE K8S scripts. Don't forget to configure the license key.

Run the following commands to stop TBMQ, migrate the database, and redeploy:

./k8s-delete-tbmq.sh
./k8s-upgrade-tbmq.sh --fromVersion=ce
./k8s-deploy-tbmq.sh

Pull the latest changes from the release branch:

git pull origin release-2.3.0

Note: Make sure any custom changes are not lost during the merge.

After pulling, run the upgrade script:

./k8s-upgrade-tbmq.sh