> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tembo.io/llms.txt
> Use this file to discover all available pages before exploring further.

# AWS

> Prepare EKS and your VPC for Tembo, apply the tembo-agent-host Terraform module, and use its outputs to configure the chart.

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](https://github.com/tembo/terraform-aws-tembo-agent-host), 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:

  ```yaml theme={null}
  apiVersion: eks.amazonaws.com/v1
  kind: IngressClassParams
  metadata:
    name: alb
  spec:
    scheme: internet-facing
  ---
  apiVersion: networking.k8s.io/v1
  kind: IngressClass
  metadata:
    name: alb
  spec:
    controller: eks.amazonaws.com/alb
    parameters:
      apiGroup: eks.amazonaws.com
      kind: IngressClassParams
      name: alb
  ```

* **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:

  ```bash theme={null}
  aws ec2 describe-instance-type-offerings --location-type availability-zone \
    --filters Name=instance-type,Values=c8id.8xlarge --query 'InstanceTypeOfferings[].Location'
  ```

* **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

```hcl theme={null}
module "tembo" {
  source = "git::https://github.com/tembo/terraform-aws-tembo-agent-host.git?ref=v0.2.2"

  cluster_name         = "<your-eks-cluster>"
  kubernetes_namespace = "tembo"
  release_name         = "tembo"

  vpc_id          = "<your-vpc-id>"
  host_subnet_ids = ["<subnet-id>", "<subnet-id>"]

  # Your Tembo URL, so browsers can upload files.
  object_storage_cors_allowed_origins = ["https://tembo.example.com"]

  # With your own Postgres or Redis, let agent hosts reach them:
  # host_access_rules = [
  #   { security_group_id = "<postgres-sg>", port = 5432, description = "Postgres from Tembo agent hosts" },
  #   { security_group_id = "<redis-sg>", port = 6379, description = "Redis from Tembo agent hosts" },
  # ]
}

output "helm_values" {
  value = module.tembo.helm_values
}
```

```bash theme={null}
terraform init
terraform apply
```

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](https://github.com/tembo/terraform-aws-tembo-agent-host#inputs) for the other options, such as `instance_types`.

***

## Configure the chart with its outputs

Save the module's Helm values:

```bash theme={null}
terraform output -json helm_values > tembo-aws.json
```

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](https://docs.tembo.io/features/self-hosted/kubernetes/deploy.md) with `tembo-aws.json` first and your own `values.yaml` after it, so yours override them. To change the agent hosts, see [Agent hosts](https://docs.tembo.io/features/self-hosted/kubernetes/configuration.md#agent-hosts); to use managed Postgres or Redis, see [Postgres and Redis](https://docs.tembo.io/features/self-hosted/kubernetes/configuration.md#postgres-and-redis).

Next, set up [GitHub](https://docs.tembo.io/features/self-hosted/kubernetes/prerequisites/github.md).

***

## Need Help?

If you run into any issues, contact [support@tembo.io](mailto:support@tembo.io).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.