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

# Upgrade to Terraform module v7

> Upgrade your self-hosted Braintrust AWS deployment from Terraform module v6 to v7, which routes API traffic to ECS and deploys the Braintrust Gateway by default.

Terraform module v7 makes ECS and the private [Braintrust Gateway](https://www.braintrust.dev/docs/admin/self-hosting/configure/gateway.md) the defaults for AWS deployments, and removes the API Lambda functions that v6 kept warm when API traffic runs on ECS. Module v7.0.0 ships data plane v2.20.0 image tags.

> [!WARNING]
>
> **Breaking change:** These variables default to `true` on v7 instead of `false`:
>
> * `enable_ecs_api`
> * `create_ai_gateway`
> * `enable_ai_gateway`
> * `use_private_ai_gateway_origin`
>
> If your configuration relies on the v6 defaults, the v7 apply moves API traffic from Lambda to ECS, deletes the APIHandler and AI Proxy Lambda functions, their public function URL, and API Gateway, and builds and enables the Gateway. Before you apply, set the variables for [your configuration](#choose-your-configuration).

> [!NOTE]
>
> Always upgrade one major version at a time. If you are on v5.x, [upgrade to v6](https://www.braintrust.dev/docs/admin/self-hosting/upgrade/v6.md) first. See the [routine upgrade guide](https://www.braintrust.dev/docs/admin/self-hosting/upgrade/routine.md) for the standard process.

## What changed

* **Omitted variables mean ECS and the Gateway.** On v6, omitted variables mean Lambda and no Gateway. On v7, the module routes API traffic to ECS, builds the Gateway, routes the API and Loop runtime through it, and points CloudFront `/v1/proxy` at it. The Gateway adds AWS charges.
* **The API Lambda functions are removed in ECS mode.** When `enable_ecs_api` is `true`, the module deletes the APIHandler and AI Proxy Lambda functions, the AI Proxy function URL, and API Gateway. The quarantine, database migration, catchup ETL, and cron Lambda functions stay. Setting `enable_ecs_api` back to `false` creates a new Lambda path with a new function URL hostname. It doesn't restore the previous functions.
* **Quarantine LLM calls use CloudFront when the AI Proxy function is gone.** Without `quarantine_proxy_url` or `use_private_gateway_quarantine_proxy`, LLM calls from custom scorers and tools go to the deployment's CloudFront `/v1/proxy` URL through the quarantine VPC's NAT gateway. If you restrict CloudFront with a WAF or a source IP allowlist, allow that NAT gateway address. To keep these calls inside your VPCs instead, see [Braintrust Gateway](https://www.braintrust.dev/docs/admin/self-hosting/configure/gateway.md).

## Before you upgrade

If you're moving to the [private Gateway](#private-gateway-default), the v7 default, finish these applies on the latest v6 release before you bump the module. For any other configuration, skip to [Choose your configuration](#choose-your-configuration).

1. Build the API ECS services. This is the first apply of the [v6 upgrade](https://www.braintrust.dev/docs/admin/self-hosting/upgrade/v6.md), with `enable_ecs_api` left at its v6 default of `false`, so customer traffic stays on Lambda.

2. Build the Gateway without moving traffic and apply:

   ```hcl theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
   create_ai_gateway             = true
   enable_ai_gateway             = false
   use_private_ai_gateway_origin = false
   enable_ecs_api                = false
   ```

3. Cut over API traffic and the Gateway together and apply:

   ```hcl theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
   enable_ecs_api                = true
   enable_ai_gateway             = true
   use_private_ai_gateway_origin = true
   ```

4. Run API requests, ingest traces, and run an eval to confirm traffic flows through ECS and the Gateway.

## Choose your configuration

Set the routing variables in your module block to match the configuration you want on v7.

### Private Gateway (default)

After the v6 applies, your configuration matches the v7 defaults. You can keep these lines or remove them:

```hcl theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
enable_ecs_api                = true
create_ai_gateway             = true
enable_ai_gateway             = true
use_private_ai_gateway_origin = true
```

### Stay on Lambda

To keep customer traffic on Lambda, set `enable_ecs_api = false`, then pick the Gateway settings that match your deployment.

> **Gateway built but not enabled**
>
> If you built the Gateway on v6 but haven't enabled it, keep `create_ai_gateway = true` so the apply doesn't destroy the Gateway load balancer and ECS service. Enable the other two variables in a later apply.
>
> ```hcl theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> enable_ecs_api                = false
> create_ai_gateway             = true
> enable_ai_gateway             = false
> use_private_ai_gateway_origin = false
> ```

> **Never built a Gateway**
>
> To keep the Gateway absent, set all four variables to `false`:
>
> ```hcl theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> enable_ecs_api                = false
> create_ai_gateway             = false
> enable_ai_gateway             = false
> use_private_ai_gateway_origin = false
> ```

> **Lambda with the Gateway enabled**
>
> ```hcl theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> enable_ecs_api = false
> ```
>
> The three Gateway variables default to `true`, so this apply builds the Gateway if it doesn't exist, enables it, and points CloudFront `/v1/proxy` at it.

### Run without the Gateway

To run on ECS without the Gateway, set all three Gateway variables to `false`:

```hcl theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
create_ai_gateway             = false
enable_ai_gateway             = false
use_private_ai_gateway_origin = false
```

Setting only `create_ai_gateway = false` fails the plan, because the other two variables default to `true`.

A deployment still on Lambda moves to ECS on this apply, which deletes the API Lambda functions, their function URL, and API Gateway. To stay on Lambda, also set `enable_ecs_api = false`.

### Use the Braintrust-hosted Gateway

To route CloudFront `/v1/proxy` to the Braintrust-hosted Gateway instead of a private one:

```hcl theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
use_global_ai_gateway_origin         = true
use_private_ai_gateway_origin        = false
create_ai_gateway                    = false
enable_ai_gateway                    = false
use_private_gateway_quarantine_proxy = false
```

Set all five variables:

* **`create_ai_gateway` and `enable_ai_gateway`**: If you omit them, the apply still builds the private Gateway and points the API and Loop runtime at it, because both default to `true`.
* **`use_private_gateway_quarantine_proxy`**: Must be `false`, because it requires `create_ai_gateway`.

Quarantine LLM calls that use the CloudFront `/v1/proxy` URL leave your data plane for the hosted Gateway. As with [Run without the Gateway](#run-without-the-gateway), a deployment still on Lambda moves to ECS on this apply unless you also set `enable_ecs_api = false`.

## Upgrade steps

**1. Bump the module to v7**

Update your module source and add the variables for the configuration you chose:

```hcl theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
module "braintrust-data-plane" {
  source = "github.com/braintrustdata/terraform-aws-braintrust-data-plane?ref=v7.0.0"

  # Variables from "Choose your configuration"

  # ... other configuration ...
}
```

**2. Review and apply**

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
terraform init -upgrade
terraform plan
```

> [!WARNING]
>
> Review the `terraform plan` output before you apply. If the plan deletes the APIHandler or AI Proxy Lambda functions, API Gateway, or the Gateway load balancer and you didn't intend it, set the routing variables explicitly before you apply. If you see something else unexpected, like deletion of a database or S3 bucket, [contact Braintrust](mailto:support@braintrust.dev) for help.

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
terraform apply
```

**3. Verify the data plane**

Exercise the data plane. Run API requests, ingest traces, and run an eval. Go to \*\* Settings\*\* > [\*\* Brainstore\*\*](https://www.braintrust.dev/app/~/configuration/brainstore) and confirm all settings under **Brainstore configuration** show green status.

## Roll back to v6

Before you roll back to a v6 release, set `enable_ecs_api = true` in your configuration. On v6 the default is `false`, so an omitted variable creates the Lambda path again, including the APIHandler and AI Proxy Lambda functions, a new function URL, and API Gateway. Set the Gateway variables explicitly too, because they default to `false` on v6.

## Next steps

* [Self-hosting releases](https://www.braintrust.dev/docs/data-plane-changelog.md): review release notes and infrastructure requirements for each data plane version.
* [Braintrust Gateway](https://www.braintrust.dev/docs/admin/self-hosting/configure/gateway.md): size the Gateway and route quarantine LLM calls through it.
* [Scaling and storage](https://www.braintrust.dev/docs/admin/self-hosting/configure/scaling.md#configure-aws-api-ecs-services): size the API ECS services.


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