Skip to main content
On AWS, Tembo runs on EKS and launches agent hosts as EC2 instances in your VPC. Prepare the cluster and network first, then apply the tembo-agent-host module, and use its outputs to configure the chart.

Before you run Terraform

Cluster

  • An EKS cluster with the EKS Pod Identity agent. EKS Auto Mode includes it. To use IAM roles for service accounts instead, set the module’s identity_type = "irsa"; the cluster then needs an IAM OIDC provider.
  • An IngressClass named alb. The AWS Load Balancer Controller creates it. On EKS Auto Mode, create it yourself:
  • An ACM certificate for your hostname, in the cluster’s region. The load balancer uses it for HTTPS.

VPC and subnets

Agent hosts launch into subnets you choose, in the cluster’s VPC:
  • Private subnets with a NAT gateway. Hosts need outbound access to your Tembo URL, Tembo’s API, object storage, LLM providers and code hosts such as GitHub.
  • Several Availability Zones that offer your instance types. The default, c8id.8xlarge, isn’t offered in every zone; when one zone runs out of capacity, the host controller tries the next. To list the zones that offer it:
  • The cluster’s API reachable from them. Hosts read their configuration through the cluster endpoint. Turn on the endpoint’s private access, so hosts reach it inside the VPC; the module opens port 443 on the cluster security group for them. With public access only, allow your NAT gateways’ addresses in the endpoint’s public access CIDRs.
The module selects subnets by ID (host_subnet_ids) or by an existing tag (host_subnet_tags), such as karpenter.sh/discovery. It doesn’t change or tag them. If you use your own Postgres or Redis instead of the chart’s, note their security groups: agent hosts connect to them too (see host_access_rules below).

Quotas

Each c8id.8xlarge host uses 32 vCPUs of the Running On-Demand Standard (A, C, D, H, I, M, R, T, Z) instances quota in the region, which also counts your cluster’s on-demand nodes. The default pool runs up to three hosts. Check the quota in Service Quotas > Amazon EC2 and request more if needed.

Permissions to apply

The identity that runs Terraform needs to read the EKS cluster and create:
  • IAM roles, inline policies and an instance profile.
  • A security group and its rules, including a rule on the cluster security group.
  • An S3 bucket and its settings.
  • EKS Pod Identity associations.

Install the module

It needs AWS provider 5.79 or later. The module creates:
  • The host controller’s role, bound to the chart’s service account through EKS Pod Identity. It can launch instances only into your subnets, with the module’s security group and instance profile, and terminate only the instances it tagged.
  • The agent hosts’ role and instance profile, with access to the install’s bucket and, by default, Session Manager.
  • The hosts’ security group: the host manager’s port (8743) from the cluster, all egress, and the hosts’ access to the Kubernetes API.
  • An S3 bucket for project images, session snapshots and file uploads, and the control plane’s role to use it. To use a bucket you have, set object_storage_bucket_name.
Set kubernetes_namespace and release_name to the namespace and release you’ll install the chart with: the roles trust only the chart’s service accounts in that namespace. See the module’s inputs for the other options, such as instance_types.

Configure the chart with its outputs

Save the module’s Helm values:
They configure the chart for the resources the module created:
  • The host controller, with its role.
  • A host class named default, with your subnets, the security group, the instance profile, c8id.8xlarge and Tembo’s stable agent host image.
  • A pool named default, of one to three hosts.
  • Object storage, with the bucket and the control plane’s role.
  • On EKS Auto Mode, the class for the load balancers agent hosts reach Postgres and Redis through.
Deploy with tembo.json first and your own values.yaml after it, so yours override them. To change the agent hosts, see Agent hosts; to use managed Postgres or Redis, see Postgres and Redis. Next, set up GitHub.

DNS

Use Route 53 private hosted zones associated with the hosts’ VPC for postgres.<your-host>, redis.<your-host> and sandbar.<your-host>. A zone for each internal hostname avoids shadowing the public app and preview names. Configure external-dns for Route 53 to watch Services and manage these zones. The chart already annotates each internal Service with its hostname, so external-dns creates and updates records when the load balancers become available. Keep public and private zone filters separate. Without external-dns, create private records from the load balancer addresses shown by kubectl -n tembo get svc.

Ingress and certificates

We use the AWS Load Balancer Controller (EKS Auto Mode), external-dns and ACM.
  • Load balancers: ingress.aws makes each Ingress an internet-facing ALB with an HTTPS redirect, and sets its health checks. On EKS Auto Mode, internal load balancers need the eks.amazonaws.com/nlb class. The module’s Helm values set it for Postgres and Redis, and Sandbar uses the same one.
  • Certificates: request ACM certificates for tembo.example.com and *.previews.tembo.example.com in the cluster’s region. The ALB finds them by name, or list their ARNs in ingress.aws.certificates. With ingress.public, also request a certificate for its hostname; list its ARN in ingress.public.certificates if needed. It can’t use Kubernetes Secrets, so cert-manager doesn’t apply here.

Need Help?

If you run into any issues, contact support@tembo.io.