Microservices setup using AWS EKS
Primeiros Passos Documentação Guias Arquitetura API FAQ

Microservices setup using AWS EKS

This guide will help you to setup ThingsBoard in microservices mode using AWS EKS. See microservices architecture page for more details about each component that will be installed. We will use Amazon RDS for managed PostgreSQL, Amazon MSK for managed Kafka and Amazon ElastiCache for managed Redis.

Install and configure tools

To deploy ThingsBoard on EKS cluster you’ll need to install kubectl, eksctl and awscli tools.

Afterwards you need to configure Access Key, Secret Key and default region. To get Access and Secret keys please follow this guide. The default region should be the ID of the region where you’d like to deploy the cluster.

1

aws configure

Step 1. Clone ThingsBoard CE K8S scripts repository

1
2

git clone https://github.com/thingsboard/thingsboard-ce-k8s.git
cd thingsboard-ce-k8s/aws/microservices

Step 2. Configure and create EKS cluster

In the cluster.yml file you can find suggested cluster configuration. Here are the fields you can change depending on your needs:

  • region - should be the AWS region where you want your cluster to be located (the default value is us-east-1)
  • availabilityZones - should specify the exact IDs of the region’s availability zones (the default value is [us-east-1a,us-east-1b,us-east-1c])
  • instanceType - the type of the instance with TB node (the default value is m5.xlarge)

Note: if you don’t make any changes to instanceType and desiredCapacity fields, the EKS will deploy 3 nodes of type m5.xlarge.

The following command will create new VPC for your ThingsBoard cluster. This guide assumes you will create new VPC. Although it is fine to use existing VPC and subnets as well. You can find more information about configuring VPC for eksctl aqui.

Command to create AWS cluster:

1

eksctl create cluster -f cluster.yml

Step 3. Create AWS load-balancer controller

Once the cluster is ready you must create AWS load-balancer controller. You can do it by following this guide. The cluster provisioning scripts will create several load balancers:

  • “tb-http-loadbalancer” - AWS ALB that is responsible for the web UI, REST API and HTTP transport;
  • “tb-mqtt-loadbalancer” - AWS NLB that is responsible for the MQTT transport;
  • “tb-coap-loadbalancer” - AWS NLB that is responsible for the CoAP transport;

Provisioning of the AWS load-balancer controller is a very important step that is required for those load balancers to work properly.

Step 4. Amazon PostgreSQL DB Configuration

You’ll need to set up PostgreSQL on Amazon RDS. ThingsBoard will use it as a main database to store devices, dashboards, rule chains and device telemetry. You may follow this guide, but take into account the following requirements:

  • Keep your postgresql password in a safe place. We will refer to it later in this guide using YOUR_RDS_PASSWORD.
  • Make sure your PostgreSQL version is latest 12.x, not 13.x yet;
  • Make sure your PostgreSQL RDS instance is accessible from the ThingsBoard cluster; The easiest way to achieve this is to deploy the PostgreSQL RDS instance in the same VPC and use ‘eksctl-thingsboard-cluster-ClusterSharedNodeSecurityGroup-*’ security group. We assume you locate it in the same VPC in this guide;
  • Make sure you use “thingsboard” as initial database name;

, and recommendations:

  • Use ‘Production’ template for high availability. It enables a lot of useful settings by default;
  • Use ‘Provisioned IOPS’ for better performance;
  • Consider creation of custom parameters group for your RDS instance. It will make change of DB parameters easier;
  • Consider deployment of the RDS instance into private subnets. This way it will be nearly impossible to accidentally expose it to the internet.
image
Make sure your PostgreSQL version is latest 12.x, not 13.x yet.
image
Keep your PosgreSQL master password in a safe place. We will refer to it later in this guide using YOUR_RDS_PASSWORD.
image
Use "Provisioned IOPS" for better performance.
image
Make sure your PostgreSQL RDS instance is accessible from the ThingsBoard cluster; The easiest way to achieve this is to deploy the PostgreSQL RDS instance in the same VPC and use "eksctl-thingsboard-cluster-ClusterSharedNodeSecurityGroup-*" security group.
image
Make sure you use "thingsboard" as initial database name.
image
Disable "auto minor version update".

Once the database switch to the ‘Available’ state, navigate to the ‘Connectivity and Security’ and copy the endpoint value. We will refer to it later in this guide using YOUR_RDS_ENDPOINT_URL.

image
Once the database switch to the "Available" state, navigate to the "Connectivity and Security" and copy the endpoint value. We will refer to it later in this guide using **YOUR_RDS_ENDPOINT_URL**.

Step 5. Amazon MSK Configuration

You’ll need to set up Kafka using Amazon MSK. ThingsBoard will use it to communicate between microservices, store unprocessed messages, etc. Kafka is useful to survive peak loads and hardware failures to make sure that all messages from devices will be processed.

Please open AWS console and navigate to MSK, press Create cluster button and choose Custom create mode.

  • Make sure your Apache Kafka version is 2.6.x;
  • Make sure your MSK instance is accessible from the ThingsBoard cluster. The easiest way to achieve this is to deploy the MSK instance in the same VPC. We also recommend to use private subnets. This way it will be nearly impossible to accidentally expose it to the internet;
  • Use m5.large or similar instance types;
  • Choose default security settings. Make sure ‘Plaintext’ mode is enabled;
  • Use default ‘Monitoring’ settings or enable ‘Enhenced topic level monitoring’.
image
Make sure your Apache Kafka version is 2.6.x.
image
Make sure your MSK instance is accessible from the ThingsBoard cluster. The easiest way to achieve this is to deploy the MSK instance in the same VPC. We also recommend to use private subnets. This way it will be nearly impossible to accidentally expose it to the internet.
image
Use m5.large or similar instance types.
image
Choose default security settings. Make sure "Plaintext" mode is enabled.
image
Use default "Monitoring" settings or enable "Enhenced topic level monitoring".

Once the MSK cluster switch to the ‘Active’ state, navigate to ‘Details’ and click ‘View client information’. Copy bootstrap server information in plaintext. We will refer to it later in this guide using YOUR_MSK_BOOTSTRAP_SERVERS_PLAINTEXT.

image
Once the MSK cluster switch to the "Active" state, navigate to "Details" and click "View client information".
image
Copy bootstrap server information in plaintext. We will refer to it later in this guide using **YOUR_MSK_BOOTSTRAP_SERVERS_PLAINTEXT**.

Step 6. Amazon ElactiCache (Redis) Configuration

You’ll need to set up Amazon ElastiCache (Redis). ThingsBoard uses cache to improve performance and avoid frequent DB reads.

Please open AWS console and navigate to ElastiCache->Redis->Create.

  • Specify Redis Engine version 6.x and node type with at least 1 GB of RAM;
  • Make sure your Redis cluster is accessible from the ThingsBoard cluster. The easiest way to achieve this is to deploy the Redis cluster in the same VPC. We also recommend to use private subnets. Use “eksctl-thingsboard-cluster-ClusterSharedNodeSecurityGroup-*” security group;
  • Disable automatic backups.
image
Specify Redis Engine version 6.x and node type with at least 1 GB of RAM.
image
Make sure your Redis cluster is accessible from the ThingsBoard cluster. The easiest way to achieve this is to deploy the Redis cluster in the same VPC. We also recommend to use private subnets. Use "eksctl-thingsboard-cluster-ClusterSharedNodeSecurityGroup-*" security group.
image
Disable automatic backups.

Once the Redis cluster switch to the ‘Available’ state, navigate to ‘Details’ and copy ‘Primary Endpoint’ without ‘:6379’ port sufix. We will refer to it later in this guide using YOUR_REDIS_ENDPOINT_URL_WITHOUT_PORT.

image
Once the Redis cluster switch to the "Available" state, navigate to "Details" and copy "Primary Endpoint" without ":6379" port sufix. We will refer to it later in this guide using **YOUR_REDIS_ENDPOINT_URL_WITHOUT_PORT**.

Edit “tb-node-db-configmap.yml” and replace YOUR_RDS_ENDPOINT_URL and YOUR_RDS_PASSWORD with the values you have obtained during step 4.

Edit “tb-kafka-configmap.yml” and replace YOUR_MSK_BOOTSTRAP_SERVERS_PLAINTEXT with the values you have obtained during step 5.

Edit “tb-redis-configmap.yml” and replace YOUR_REDIS_ENDPOINT_URL_WITHOUT_PORT with the values you have obtained during step 6.

Step 8. Configure HTTPS (Optional)

Use AWS Certificate Manager to create or import SSL certificate. After creation/import you’ll need to uncomment the ‘alb.ingress.kubernetes.io/certificate-arn’ setting and paste certificate’s ARN instead of YOUR_HTTPS_CERTIFICATE_ARN in the routes.yml file:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

...
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  namespace: thingsboard
  name: tb-http-loadbalancer
  annotations:
    kubernetes.io/ingress.class: alb
    alb.ingress.kubernetes.io/scheme: internet-facing
    alb.ingress.kubernetes.io/target-type: ip
    # Uncomment the following line to enable HTTPS. Don't forget to replace YOUR_CERTIFICATE_ARN with the correct value
    # See https://docs.aws.amazon.com/elasticloadbalancing/latest/application/create-https-listener.html#https-listener-certificates for more info
    # alb.ingress.kubernetes.io/certificate-arn: YOUR_CERTIFICATE_ARN
...

Step 9. Configure MQTTS (Optional)

One-way TLS

The simplest way to configure MQTTS is to make your MQTT load balancer (AWS NLB) to act as a TLS termination point. This way we setup the one-way TLS connection, where the traffic between your devices and load balancers is encrypted, and the traffic between your load balancer and MQTT Transport is not encrypted. There should be no security issues, since the ALB/NLB is running in your VPC. The only major disadvantage of this option is that you can’t use “X.509 certificate” MQTT client credentials, since information about client certificate is not transferred from the load balancer to the ThingsBoard MQTT Transport service.

To enable the one-way TLS:

  • Use AWS Certificate Manager to create or import SSL certificate.
  • Locate 2 places marked as “Uncomment the following lines to enable one-way MQTTS” in the “routes.yml” and paste certificate’s ARN instead of YOUR_MQTTS_CERTIFICATE_ARN.

Two-way TLS

The more complex way to enable MQTTS is to obtain valid (signed) TLS certificate and configure it in the MQTT Transport. The main advantage of this option is that you may use it in combination with “X.509 certificate” MQTT client credentials.

To enable the two-way TLS:

Follow this guide to create a .jks file with the SSL certificate. Afterwards, you need to set MQTT_SSL_KEY_STORE_PASSWORD and MQTT_SSL_KEY_PASSWORD environment variables in the tb-services.yml file to the corresponding key-store and certificate key passwords.

You’ll need to create a config-map with your JKS file, you can do it by calling command:

1
2

kubectl create configmap tb-mqtts-config \
             --from-file=server.jks=YOUR_JKS_FILENAME.jks -o yaml --dry-run=client | kubectl apply -f -

where YOUR_JKS_FILENAME is the name of your .jks file. Then, uncomment all sections in the ‘tb-services.yml’ file that are marked with “Uncomment the following lines to enable two-way MQTTS”. Also, uncomment sections in the ‘routes.yml’ file that is marked with the same “Uncomment the following lines to enable two-way MQTTS” comment.

Step 10. CPU and Memory resources allocation

The scripts have preconfigured values of resources for each service. You can change them in .yml files under resources submenu.

Note: if you want to allocate more resources you’ll need to increase the number of Amazon nodes or use larger machines.

Recommended CPU/memory resources allocation:

  • TB Node: 1.0 CPU / 2Gi memory
  • TB HTTP Transport: 0.5 CPU / 0.5Gi memory
  • TB MQTT Transport: 0.5 CPU / 0.5Gi memory
  • TB COAP Transport: 0.5 CPU / 0.5Gi memory
  • TB Web UI: 0.1 CPU / 100Mi memory
  • JS Executor: 0.1 CPU / 100Mi memory
  • Zookeeper: 0.1 CPU / 0.5Gi memory

Step 11. Installation

Execute the following command to run the initial setup of the database. This command will launch short-living ThingsBoard pod to provision necessary DB tables, indexes, etc

1

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

Where:

  • --loadDemo - optional argument. Whether to load additional demo data.

After this command finish you should see the next line in the console:

1

Installation finished successfully!

Otherwise, please check if you set the PostgreSQL URL in the tb-node-db-configmap.yml correctly.

Step 12. Starting

Execute the following command to deploy ThingsBoard services:

1

 ./k8s-deploy-resources.sh

After few minutes you may call kubectl get pods. If everything went fine, you should be able to see:

  • 3x tb-coap-transport
  • 3x tb-http-transport
  • 3x tb-mqtt-transport
  • 5x tb-js-executor
  • 3x tb-node
  • 2x tb-web-ui
  • 3x zookeeper.

Every pod should be in the READY state.

Step 13. Validate the setup

Validate Web UI access

Now you can open ThingsBoard web interface in your browser using DNS name of the load balancer.

You can see DNS name (the ADDRESS column) of the HTTP load-balancer using command:

1

kubectl get ingress

You should see the similar picture:

image

Use the following default credentials:

  • System Administrator: sysadmin@thingsboard.org / sysadmin

If you installed DataBase with demo data (using --loadDemo flag) you can also use the following credentials:

  • Tenant Administrator: tenant@thingsboard.org / tenant
  • Customer User: customer@thingsboard.org / customer

Validate MQTT/CoAP access

To connect to the cluster via MQTT or COAP you’ll need to get corresponding service, you can do it with command:

1

kubectl get service

You should see the similar picture:

image

There are two load-balancers:

  • tb-mqtt-loadbalancer-external - for MQTT protocol
  • tb-coap-loadbalancer-external - for COAP protocol

Use EXTERNAL-IP field of the load-balancers to connect to the cluster.

Troubleshooting

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

1

kubectl logs -f tb-node-0

Or use kubectl get pods to see the state of the pods. Or use kubectl get services to see the state of all the services. Or use kubectl get deployments to see the state of all the deployments. See kubectl Cheat Sheet command reference for details.

Upgrading to new ThingsBoard version

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

In case when database upgrade is needed, execute the following commands:

1

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

Where:

  • FROM_VERSION - from which version upgrade should be started. See Upgrade Instructions for valid fromVersion values.

Note: You may optionally stop the tb-node pods while you run the upgrade of the database. 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 tb-nodes to be stopped.

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

1

./k8s-deploy-resources.sh

Cluster deletion

Execute the following command to delete all ThingsBoard pods:

1

./k8s-delete-resources.sh

Execute the following command to delete all ThingsBoard pods and configmaps:

1

./k8s-delete-all.sh

Execute the following command to delete EKS cluster (you should change the name of the cluster and zone):

1

eksctl delete cluster -r us-east-1 -n thingsboard -w