GKE Monolith Setup

This guide walks you through deploying ThingsBoard in monolith mode on Google Kubernetes Engine. We use Google Cloud SQL for managed PostgreSQL.

Install kubectl and gcloud. See before you begin for more info.

Create a new GCP project (recommended) or choose an existing one:

gcloud init

gcloud services enable container.googleapis.com sql-component.googleapis.com sqladmin.googleapis.com

Verify that you can pull the images from Docker Hub:

docker pull thingsboard/tb-node:4.4.0
docker pull thingsboard/tb-web-report:4.4.0

Clone the repository containing the Kubernetes deployment scripts:

git clone -b release-4.4.0 https://github.com/thingsboard/thingsboard-pe-k8s.git --depth 1
cd thingsboard-pe-k8s/gcp/monolith

export GCP_PROJECT=$(gcloud config get-value project)
export GCP_REGION=us-central1
export GCP_ZONE=us-central1-a
export GCP_NETWORK=default
export TB_CLUSTER_NAME=tb
export TB_DATABASE_NAME=tb-db
echo "Project: $GCP_PROJECT, region: $GCP_REGION, zone: $GCP_ZONE, network: $GCP_NETWORK, cluster: $TB_CLUSTER_NAME, database: $TB_DATABASE_NAME"

Create a zonal cluster with 1 node of e2-standard-4 machine type:

gcloud container clusters create $TB_CLUSTER_NAME \
  --release-channel stable \
  --zone $GCP_ZONE \
  --node-locations $GCP_ZONE \
  --network=$GCP_NETWORK \
  --enable-ip-alias \
  --num-nodes=1 \
  --node-labels=role=main \
  --machine-type=e2-standard-4

Alternatively, see the custom cluster setup guide.

gcloud container clusters get-credentials $TB_CLUSTER_NAME --zone $GCP_ZONE

Enable service networking:

gcloud services enable servicenetworking.googleapis.com --project=$GCP_PROJECT

gcloud compute addresses create google-managed-services-$GCP_NETWORK \
  --global \
  --purpose=VPC_PEERING \
  --prefix-length=16 \
  --network=projects/$GCP_PROJECT/global/networks/$GCP_NETWORK

gcloud services vpc-peerings connect \
  --service=servicenetworking.googleapis.com \
  --ranges=google-managed-services-$GCP_NETWORK \
  --network=$GCP_NETWORK \
  --project=$GCP_PROJECT

Create a PostgreSQL 16 instance. Recommendations:

• Use the same region and VPC network as your GKE cluster
• Use private IP address and disable public IP
• Use highly available instance for production, single zone for development
• At least 2 vCPUs and 7.5 GB RAM

gcloud beta sql instances create $TB_DATABASE_NAME \
  --database-version=POSTGRES_16 \
  --region=$GCP_REGION --availability-type=regional \
  --no-assign-ip --network=projects/$GCP_PROJECT/global/networks/$GCP_NETWORK \
  --cpu=2 --memory=7680MB

Note the IP address (YOUR_DB_IP_ADDRESS) from the command output.

gcloud sql users set-password postgres \
  --instance=$TB_DATABASE_NAME \
  --password=secret

gcloud sql databases create thingsboard --instance=$TB_DATABASE_NAME

Using Cassandra is optional. We recommend it if you plan to insert more than 5K data points per second or want to optimize storage space.

Create 3 separate node pools with 1 node per zone. At least 4 vCPUs and 16 GB of RAM is recommended.

gcloud container node-pools create cassandra1 --cluster=$TB_CLUSTER_NAME --zone=$GCP_ZONE --node-locations=$GCP_ZONE1 \
  --node-labels=role=cassandra --num-nodes=1 --min-nodes=1 --max-nodes=1 --machine-type=e2-standard-4
gcloud container node-pools create cassandra2 --cluster=$TB_CLUSTER_NAME --zone=$GCP_ZONE --node-locations=$GCP_ZONE2 \
  --node-labels=role=cassandra --num-nodes=1 --min-nodes=1 --max-nodes=1 --machine-type=e2-standard-4
gcloud container node-pools create cassandra3 --cluster=$TB_CLUSTER_NAME --zone=$GCP_ZONE --node-locations=$GCP_ZONE3 \
  --node-labels=role=cassandra --num-nodes=1 --min-nodes=1 --max-nodes=1 --machine-type=e2-standard-4

Create the namespace, then deploy Cassandra:

kubectl apply -f tb-namespace.yml
kubectl config set-context $(kubectl config current-context) --namespace=thingsboard
kubectl apply -f receipts/cassandra.yml

echo "  DATABASE_TS_TYPE: cassandra" >> tb-node-db-configmap.yml
echo "  CASSANDRA_URL: cassandra:9042" >> tb-node-db-configmap.yml
echo "  CASSANDRA_LOCAL_DATACENTER: $GCP_REGION" >> tb-node-db-configmap.yml

Create the ThingsBoard keyspace inside Cassandra:

kubectl exec -it cassandra-0 -- bash -c "cqlsh -e \
    \"CREATE KEYSPACE IF NOT EXISTS thingsboard \
    WITH replication = { \
        'class' : 'NetworkTopologyStrategy', \
        'us-central1' : '3' \
    };\""

We assume you have already chosen your subscription plan or decided to purchase a perpetual license. If not, navigate to the pricing page.

Create a docker secret with your license key:

export TB_LICENSE_KEY=PUT_YOUR_LICENSE_KEY_HERE
kubectl create -n thingsboard secret generic tb-license --from-literal=license-key=$TB_LICENSE_KEY

Edit tb-node-db-configmap.yml and replace YOUR_DB_IP_ADDRESS and YOUR_DB_PASSWORD:

nano tb-node-db-configmap.yml

Run the installation:

./k8s-install-tb.sh

After this command finishes you should see:

Installation finished successfully!

./k8s-deploy-resources.sh

After a few minutes, call kubectl get pods. If everything went fine, you should see tb-node-0 pod in the READY state.

You have 3 options:

• HTTP — recommended for development.
• HTTPS — recommended for production. Uses Google-managed SSL certificate.
• Transparent — forwards traffic to ThingsBoard HTTP/HTTPS ports. Requires your own SSL certificate.

kubectl apply -f receipts/http-load-balancer.yml

kubectl get ingress

gcloud compute addresses create thingsboard-http-lb-address --global

kubectl apply -f receipts/https-load-balancer.yml

kubectl describe managedcertificate managed-cert

kubectl apply -f receipts/transparent-http-load-balancer.yml

kubectl apply -f receipts/mqtt-load-balancer.yml

The load balancer forwards all TCP traffic for ports 1883 and 8883.

For MQTT over SSL, follow the MQTT over SSL guide to configure the required environment variables in tb-node.yml.

kubectl apply -f receipts/udp-load-balancer.yml

The load balancer forwards UDP traffic for ports 5683–5688 (CoAP and LwM2M protocols).

For CoAP over DTLS, follow the CoAP over DTLS guide. For LwM2M over DTLS, follow the LwM2M over DTLS guide.

kubectl apply -f receipts/edge-load-balancer.yml

The load balancer forwards all TCP traffic on port 7070.

After launching ThingsBoard, open the web UI at the load balancer address. ThingsBoard prompts you to create your System Administrator account — the account that manages the platform itself (tenants, system settings, platform-wide resources).

1. Enter Email, Password, and Confirm password.
2. The Set up a demo tenant option is selected by default: it creates a ready-made tenant with dashboards, devices, and rule chains for exploring the platform before building your own solution. Clear it if you want to start with an empty platform.
3. Click Create account. You are signed in as the system administrator.

Your ThingsBoard instance is now installed and running.

Confirm that the load balancers created in Step 9 are provisioned and reachable, and note their addresses — you need them to open the web UI and to connect devices.

Check the status of the ingress you created for the HTTP(S) load balancer:

kubectl get ingress

Once an external IP address is assigned, use it to open the ThingsBoard web interface in your browser.

List the cluster services to find the external IP addresses assigned to the MQTT and UDP load balancers you configured:

kubectl get service

Use the external IP of each load balancer to connect devices over MQTT, CoAP, or LwM2M.

Pull the Trendz images from Docker Hub:

docker pull thingsboard/trendz:1.16.0
docker pull thingsboard/trendz-python-executor:1.16.0

Edit trendz/trendz-secret.yml and replace YOUR_DB_IP_ADDRESS and YOUR_DB_PASSWORD, then apply:

kubectl apply -f ./trendz/trendz-secret.yml
kubectl apply -f ./trendz/trendz-create-db.yml

Check logs:

kubectl logs job/trendz-create-db -n thingsboard

./k8s-deploy-trendz.sh

After this command finishes you should see:

Trendz installed successfully!

Stream the logs of the ThingsBoard node pod to diagnose startup or runtime issues:

kubectl logs -f tb-node-0

See the kubectl Cheat Sheet for more details.

Delete ThingsBoard pods and load balancers:

./k8s-delete-resources.sh

Delete all data including database:

./k8s-delete-all.sh

With ThingsBoard running, these concept guides help you build your first solution:

• Getting Started — a guided walkthrough of the platform after installation.
• Multi-Tenancy & Hierarchy — how tenants, customers, and users are organized.
• Digital Twin Model — how devices and assets are modeled in the platform.
• Data Processing — how the Rule Engine transforms and routes incoming data.
• Alarms & Notifications — how to detect conditions and notify users.
• Data Visualization — how to build dashboards and widgets.