Install Tembo Self Hosted on AWS EKS

This guide describes the steps to install Tembo Self Hosted on AWS, which allows you to deploy a high-performance, fully-extensible managed Postgres service within an AWS Elastic Kubernetes Service (EKS) cluster.

Step 1: Obtain prerequisites

Before starting this tutorial, you must install and configure the following tools and resources that you need to create and manage Tembo Self Hosted on an Amazon EKS cluster.

The command-line tools for AWS (awscli) and for Kubernetes (kubectl).
The command-line tool for Amazon EKS (eksctl), used to create and manage your Tembo cluster on EKS.
The Helm CLI.
Obtain a Clerk authentication key from Tembo.

Step 2: Choose and setup a base domain

For the Tembo services, you will need to select a base domain, such as tembo.mydomain.com.

Once you have chosen your base domain, you must ensure you have the capacity to add and modify DNS records for it.

With this setup, your users will be able to access various subdomains to manage, monitor and run Postgres on the platform:

Software UI: app.tembo.mydomain.com
Backend requests: api.tembo.mydomain.com
Tembo Dataplane: dataplane.tembo.mydomain.com

Step 3: Create an EKS Kubernetes cluster

To create an EKS cluster named tembo-cluster with a minimum of three nodes, run the following command:

export CLUSTER_NAME=tembo-cluster
export NODES_MIN=3
export NODES_MAX=6
export NODE_TYPE=m5a.large
export REGION=us-east-1

eksctl create cluster --name $CLUSTER_NAME --nodes-min $NODES_MIN --nodes-max $NODES_MAX --node-type $NODE_TYPE --region $REGION

Feel free to adjust the parameters as needed to suit your requirements.

For further information, see Getting started with Amazon EKS.

Step 4: Enable IAM OIDC Provider

To enable the IAM OIDC provider for your cluster, run the following command:

eksctl utils associate-iam-oidc-provider --cluster $CLUSTER_NAME --region $REGION --approve

Step 5: Creating the Amazon EBS CSI driver IAM role

To create an IAM role for the Amazon EBS CSI driver, run the following command:

export IAM_ROLE_NAME=AmazonEKS_EBS_CSI_DriverRole_tembo

eksctl create iamserviceaccount \
    --name ebs-csi-controller-sa \
    --namespace kube-system \
    --cluster $CLUSTER_NAME \
    --role-name $IAM_ROLE_NAME \
    --role-only \
    --attach-policy-arn arn:aws:iam::aws:policy/service-role/AmazonEBSCSIDriverPolicy \
    --region $REGION \
    --approve

We now need to find out the ARN for the role we just created. Assuming the role name is AmazonEKS_EBS_CSI_DriverRole_tembo, we can run the following to identify the ARN:

$ aws iam list-roles | grep AmazonEKS_EBS_CSI_DriverRole_tembo
            "RoleName": "AmazonEKS_EBS_CSI_DriverRole_tembo",
            "Arn": "arn:aws:iam::123456789012:role/AmazonEKS_EBS_CSI_DriverRole_tembo"

This will be necessary for the next step.

Step 6: Add the Amazon EBS CSI driver add-on

export SERVICE_ACCOUNT_ROLE_ARN=arn:aws:iam::123456789012:role/AmazonEKS_EBS_CSI_DriverRole_tembo

eksctl create addon \
     --name aws-ebs-csi-driver \
     --cluster $CLUSTER_NAME \
     --service-account-role-arn $SERVICE_ACCOUNT_ROLE_ARN \
     --region $REGION \
     --force

For --service-account-role-arn, supply the ARN created in Step 5.

Step 7: Install Cert Manager

Install cert-manager

helm install \
  cert-manager jetstack/cert-manager \
  --namespace cert-manager \
  --create-namespace \
  --version v1.14.4 --set installCRDs=true

Step 8: Update the StorageClass to allow for volume expansion

This is necessary for increasing storage size for Postgres instances.

kubectl patch storageclass gp2 -p '{"allowVolumeExpansion": true}'

Step 9: Install the Tembo Self Hosted Helm chart

Clone the Tembo Self Hosted repository:

git clone https://github.com/tembo-io/tembo-self-hosted

Now, within the cloned tembo-self-hosted directory, create a file my-values.yaml with the following content:

global:
  baseDomain: tembo.mydomain.com
  monitoringEnabled: true
  conductorEnabled: false
tembo:
  cpWebserver:
    env:
      - name: CLERK_SECRET_KEY
        value: <secret-key>
      - name: CLERK_WEBHOOK_SIGNING_SECRET
        value: <signing-secret>
      - name: STRIPE_SECRET_KEY
        value: <secret-key>
      - name: STRIPE_WEBHOOK_SIGNING_SECRET
        value: <signing-secret>
      - name: METRONOME_SECRET_KEY
        value: <secret-key>

The base domain should be the same one created in Step 2.

Now, let’s install the Tembo Self Hosted Helm chart in your EKS cluster:

helm install tembo . -f my-values.yaml -n tembo --create-namespace

Let’s now enable the conductor component:

global:
  baseDomain: tembo.mydomain.com
  monitoringEnabled: true
  conductorEnabled: true

Upgrade the Self Hosted Helm chart so that changes take effect:

helm upgrade tembo . -f my-values.yaml -n tembo

Step 10: Check the status of the installation

❯ kubectl get po
NAME                                         READY   STATUS      RESTARTS      AGE
control-plane-1                              1/1     Running     0             82m
control-plane-queue-1                        1/1     Running     0             79m
tembo-cloudnative-pg-749dcfc655-756mm        1/1     Running     0             83m
tembo-conductor-fb7878d7-tvh94               1/1     Running     0             77m
tembo-conductor-watcher-7ff9547686-6sld8     1/1     Running     0             77m
tembo-controller-57899fffc4-d4j55            1/1     Running     0             82m
tembo-cp-reconciler-76bd8777b6-z2nq8         1/1     Running     0             81m
tembo-cp-service-75bccdddbd-b8xbk            1/1     Running     0             78m
tembo-cp-webserver-686fb69bb5-w5g6g          1/1     Running     0             78m
tembo-dataplane-webserver-7f9bd5cbf7-gkk2w   1/1     Running     0             83m
tembo-init-cp-db-lxl2t                       0/1     Completed   0             83m
tembo-init-cp-queue-db-lljgr                 0/1     Completed   0             83m
tembo-label-namespace-ggnml                  0/1     Completed   0             83m
tembo-pod-init-74975dbcb8-d9jpk              1/1     Running     0             83m
tembo-tembo-ui-685ccc9996-n8tmv              1/1     Running     0             83m

Step 11: Configure DNS for Traefik’s Load Balancer

To properly route traffic to your Traefik load balancer, you need to configure a DNS CNAME record through your DNS provider. Follow the steps below to create a wildcard CNAME record, which is essential because each PostgreSQL instance has its own subdomain for its connection string.

Access Your DNS Provider: Log in to your DNS provider’s management console.
Create a Wildcard CNAME Record: Set up a wildcard CNAME record (e.g., *.tembo.mydomain.com). This will cover all subdomains for your PostgreSQL instances.
Use the External IP: Point the wildcard CNAME record to the external IP of your Traefik load balancer. This external IP can be found using the command below.

kubectl get svc -n traefik
NAME      TYPE           CLUSTER-IP      EXTERNAL-IP                                                                      PORT(S)                                     AGE
traefik   LoadBalancer   10.200.50.100   abcdef1234567890abcdef1234567890-1234567890abcdef.elb.us-west-1.amazonaws.com   1234:56789/TCP,80:12345/TCP,443:23456/TCP   45m

If you’re using Amazon Route 53, the configuration should look something like the image below. For more detailed information, refer to Creating Records Using the Amazon Route 53 Console.

Configuring-DNS-using-Route-53

Verify DNS Settings: After creating the CNAME record, verify that the DNS settings are correctly propagating and resolving.

You can use nslookup to check if your DNS settings are working correctly:

nslookup test.tembo.mydomain.com
;; Got recursion not available from 2001:4860:4860::8888, trying next server
;; Got recursion not available from 2001:4860:4860::8844, trying next server
Server:		8.8.8.8
Address:	8.8.8.8#53

Non-authoritative answer:
Name:	test.tembo.mydomain.com
Address: 203.0.113.10
Name:	test.tembo.mydomain.com
Address: 203.0.113.20

Step 12: Access the Tembo Self Hosted

Access the Tembo Self Hosted UI by visiting http://app.tembo.mydomain.com in your browser. Replace tembo.mydomain.com with your domain name chosen in Step 2.