AWS EKS Monolith Setup

This guide walks you through deploying ThingsBoard CE in monolith mode on AWS EKS. We use Amazon RDS for managed PostgreSQL.

The advantage of monolith deployment via K8S compared to Docker Compose is that in case of an AWS instance outage, K8S will restart the service on another instance.

Install kubectl, eksctl, and AWS CLI.

Configure your AWS credentials. To get Access and Secret keys, follow this guide. The default region should be the ID of the region where you want to deploy the cluster.

aws configure

git clone -b release-4.3 https://github.com/thingsboard/thingsboard-ce-k8s.git
cd thingsboard-ce-k8s/aws/monolith

In the cluster.yml file you can find the suggested cluster configuration. Key fields you can change:

Create the cluster:

eksctl create cluster -f cluster.yml

Once the cluster is ready, create the AWS load-balancer controller by following this guide.

The cluster provisioning scripts create several load balancers:

Set up PostgreSQL on Amazon RDS. ThingsBoard uses it as the main database for devices, dashboards, rule chains, and device telemetry. Follow this guide, but take into account the following requirements:

• Keep your PostgreSQL password in a safe place. We will refer to it later as YOUR_RDS_PASSWORD.
• Make sure your PostgreSQL version is latest 16.x.
• Make sure your PostgreSQL RDS instance is accessible from the ThingsBoard cluster. The easiest way is to deploy the RDS instance in the same VPC and use the eksctl-thingsboard-cluster-ClusterSharedNodeSecurityGroup-* security group.
• Make sure you use “thingsboard” as the initial database name. If you do not specify a database name, Amazon RDS does not create one.

Recommendations:

• Use Production template for high availability.
• Use Provisioned IOPS for better performance.
• Consider creating a custom parameters group for your RDS instance.
• Consider deploying the RDS instance into private subnets.

Make sure your PostgreSQL version is latest 16.x. Keep your PostgreSQL master password in a safe place. Use "Provisioned IOPS" for better performance. Deploy the RDS instance in the same VPC and use the cluster shared security group. Use "thingsboard" as initial database name. Disable "auto minor version update".

Once the database switches to the Available state, navigate to Connectivity and Security and copy the endpoint value. We will refer to it as YOUR_RDS_ENDPOINT_URL.

Edit tb-node-db-configmap.yml and replace YOUR_RDS_ENDPOINT_URL and YOUR_RDS_PASSWORD.

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.

eksctl create nodegroup --config-file=<path> --include='cassandra-*'

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

Don’t forget to replace YOUR_AWS_REGION with the name of your AWS region.

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

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

Execute the following command to run the initial setup of the database:

./k8s-install-tb.sh --loadDemo

Where --loadDemo is an optional argument to load additional demo data.

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 2 options:

• HTTP — recommended for development.
• HTTPS — recommended for production. Acts as an SSL termination point.

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

Check the status:

kubectl get ingress

Use the address to access the HTTP web UI (port 80) and connect devices via HTTP API.

Default credentials:

• System Administrator: [email protected] / sysadmin
• Tenant Administrator: [email protected] / tenant (if demo data loaded)
• Customer User: [email protected] / customer (if demo data loaded)

Use AWS Certificate Manager to create or import an SSL certificate.

nano receipts/https-load-balancer.yml

Replace YOUR_HTTPS_CERTIFICATE_ARN with your certificate ARN, then deploy:

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

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

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

Make the AWS NLB act as a TLS termination point.

nano receipts/mqtts-load-balancer.yml

Replace YOUR_MQTTS_CERTIFICATE_ARN, then deploy:

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

Follow the MQTT over SSL guide to create a .pem file.

kubectl create configmap tb-mqtts-config \
 --from-file=server.pem=YOUR_PEM_FILENAME \
 --from-file=mqttserver_key.pem=YOUR_PEM_KEY_FILENAME \
 -o yaml --dry-run=client | kubectl apply -f -

Uncomment the MQTTS sections in tb-node.yml, then apply:

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

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

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

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

The load balancer forwards all TCP traffic on port 7070. Use the external IP as CLOUD_RPC_HOST in Edge connection parameters.

kubectl get ingress

Use the address to open the ThingsBoard web interface.

kubectl get service

Use the EXTERNAL-IP of tb-mqtt-loadbalancer-external or tb-coap-loadbalancer-external to connect.

kubectl logs -f tb-node-0

See the kubectl Cheat Sheet for more details.

Merge your local changes with the latest release branch from the repo you cloned in Step 1.

If a database upgrade is needed:

./k8s-upgrade-tb.sh --fromVersion=[FROM_VERSION]

Where FROM_VERSION is the starting version. See Upgrade Instructions for valid fromVersion values. You must upgrade versions one by one.

Once completed, re-deploy resources:

./k8s-deploy-resources.sh

./k8s-delete-resources.sh
./k8s-delete-all.sh
eksctl delete cluster -r us-east-1 -n thingsboard -w