> ## 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.

# GCP

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

On GCP, Tembo runs on GKE and launches agent hosts as Compute Engine instances in your VPC. Prepare the projects, cluster and network first, then apply the [`tembo-agent-host` module for Google Cloud](https://github.com/tembo/terraform-google-tembo-agent-host), and use its outputs to configure the chart.

***

## Before you run Terraform

### Projects and APIs

* **A project for agent hosts.** The host controller can create instances anywhere in the hosts' project, and change or delete only its own. We recommend a project of its own for agent hosts: set it as the module's `host_project_id`. Otherwise hosts run in the cluster's project.
* **APIs enabled** in those projects: Compute Engine, IAM, IAM Service Account Credentials and Cloud Storage (`compute.googleapis.com`, `iam.googleapis.com`, `iamcredentials.googleapis.com`, `storage.googleapis.com`).

### Cluster

* **A VPC-native GKE cluster** (Autopilot or Standard) **with Workload Identity**. Autopilot clusters always have it.
* **Ingress:** the chart serves Tembo through GKE's Ingress with a Google-managed certificate (`ingress.gke.enabled`), so you don't need a certificate in advance. GKE issues it once your hostname resolves to the Ingress.

### VPC and subnetwork

Agent hosts launch into a subnetwork you choose, in the cluster's VPC:

* **Cloud NAT and Private Google Access.** Hosts have no external addresses. They need NAT for egress to your Tembo URL, Tembo's API, LLM providers and code hosts such as GitHub, and Private Google Access for Cloud Storage and IAM.
* **The cluster's control plane reachable from it.** Hosts read their configuration through the Kubernetes API, at the cluster's private endpoint. If the cluster enforces master authorized networks on its private endpoint, add the subnetwork's range to them. Hosts in a different region than the cluster need the control plane's global access.
* **Your own Postgres or Redis**, if you use them instead of the chart's, must accept connections from the subnetwork. Hosts reach the chart's bundled Postgres and Redis through internal load balancers.

The module reads the subnetwork and doesn't change it. It creates the firewall rule that lets the cluster's pods and nodes reach the hosts' manager on port 8743; for a Shared VPC subnetwork, it creates it in the network's host project.

### Organization policies

* `compute.disableNestedVirtualization` not enforced on the hosts' project: hosts run agents in VMs.
* `compute.requireShieldedVm` not enforced: the agent host image boots with legacy BIOS.
* If you restrict `compute.trustedImageProjects`, allow Tembo's image project, `projects/tembo-prod`.

### Quotas

Each host needs 32 vCPUs and 1,500 GB of local SSD, times the pool's maximum hosts (three by default):

* N2 CPUs and local SSD in the hosts' region. The defaults often cover a few hosts.
* Persistent Disk SSD in the hosts' region: each host's 100 GB boot disk counts toward it, as do GKE's node disks. It's 500 GB in new projects.
* CPUs (all regions), a project-wide limit that also counts the cluster's nodes. It's 32 in new projects, which isn't enough for a single host.

### Permissions to apply

Apply the module as the projects' Owner, or with these roles, besides read access to the cluster (`roles/container.clusterViewer`):

| Project | Roles |
| - | - |
| The cluster's project | `roles/iam.serviceAccountAdmin`, `roles/storage.admin` |
| The hosts' project | `roles/iam.serviceAccountAdmin`, `roles/iam.roleAdmin`, `roles/resourcemanager.projectIamAdmin` |
| The subnetwork's project | `roles/compute.networkAdmin`, `roles/compute.securityAdmin` |

Editor isn't enough: it can't create the controller's custom roles or set IAM on the subnetwork.

***

## Install the module

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

  project_id           = "<your-project>"
  cluster_name         = "<your-gke-cluster>"
  cluster_location     = "us-central1"
  kubernetes_namespace = "tembo"
  release_name         = "tembo"

  # A project of its own for agent hosts (recommended).
  # host_project_id = "<your-hosts-project>"

  host_subnetwork = "projects/<your-project>/regions/us-central1/subnetworks/<hosts>"

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

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

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

It needs Google provider 6.0 or later. The module creates:

* **The host controller's service account**, bound to the chart's service account with Workload Identity. It can change and delete only instances and disks named with your install's prefix, launch them only into your subnetwork, and attach only the hosts' service account.
* **The agent hosts' service account**, with access to the install's bucket.
* **The firewall rule** for the hosts' manager.
* **A GCS bucket** for project images, session snapshots and file uploads, and the control plane's service account 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 service accounts trust only the chart's service accounts in that namespace. See the [module's README](https://github.com/tembo/terraform-google-tembo-agent-host) for the other options, such as machine types.

New IAM bindings can take a few minutes to take effect; pods that start before then retry.

***

## Configure the chart with its outputs

Save the module's Helm values:

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

They configure the chart for the resources the module created:

* The host controller, with its service account, the hosts' project and your install's instance name prefix.
* A host class named `default`, with your subnetwork, the hosts' service account, `n2-custom-32-65536` with four local SSDs, 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 service account.

[Deploy](https://docs.tembo.io/features/self-hosted/kubernetes/deploy.md) with `tembo-gcp.json` first and your own `values.yaml` after it, so yours override them. To change the agent hosts, such as their machine type, 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.