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.
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
Eachc8id.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
- 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.
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:- The host controller, with its role.
- A host class named
default, with your subnets, the security group, the instance profile,c8id.8xlargeand Tembo’sstableagent 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.
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 forpostgres.<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.awsmakes each Ingress an internet-facing ALB with an HTTPS redirect, and sets its health checks. On EKS Auto Mode, internal load balancers need theeks.amazonaws.com/nlbclass. The module’s Helm values set it for Postgres and Redis, and Sandbar uses the same one. - Certificates: request ACM certificates for
tembo.example.comand*.previews.tembo.example.comin the cluster’s region. The ALB finds them by name, or list their ARNs iningress.aws.certificates. Withingress.public, also request a certificate for its hostname; list its ARN iningress.public.certificatesif needed. It can’t use Kubernetes Secrets, so cert-manager doesn’t apply here.