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

# Upgrade to Terraform module v6.0

> Upgrade your self-hosted Braintrust AWS deployment from Terraform module v5.x to v6.0

Terraform module v6.0 moves the Braintrust API and AI Proxy workloads from Lambda to ECS. For high-traffic data planes, ECS costs about 90% less than Lambda. This is an AWS-only infrastructure change and does not affect the data plane version. The module continues to ship data plane v2.7.1 images.

<Note>
  Always upgrade one major version at a time. If you are on v4.x, upgrade to v5.x first before upgrading to v6.0. See the [routine upgrade guide](/admin/self-hosting/upgrade/routine) for the standard process.
</Note>

## What changed

APIHandler and AIProxy now run as ECS services alongside the existing Lambdas. The ECS API is split into three services for different workload types:

* `braintrust-api` — general API traffic
* `braintrust-api-ingest` — ingestion paths (`/logs3`, `/otel/v1/traces`)
* `braintrust-api-background` — background paths (evals, function invoke, proxy)

During the transition, the API Lambdas remain deployed and are kept warm. A future module release removes them.

<Note>
  After cutover, none of the primary Braintrust services handling traffic run on Lambda. Braintrust continues to use Lambda only for small one-off maintenance tasks, such as database migrations and other automations.
</Note>

## Upgrade steps

<Steps>
  <Step title="Bump the module to v6.0 and apply">
    Update your module source to v6.0.0, leaving `enable_ecs_api` at its default (`false`):

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

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

    The ECS services use new variables. If you customized the Lambda equivalents on an earlier module version, carry those values into the ECS variables before you apply, or the ECS services will start without them:

    * Values in `service_extra_env_vars.APIHandler` or `service_extra_env_vars.AIProxy` must be duplicated into `braintrust_api_extra_env_vars`.
    * A version pinned with `lambda_version_tag_override` must be copied into `braintrust_api_version_override`.

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

    <Warning>
      Carefully review the output of `terraform plan` before applying. If you see something unexpected, like deletion of a database or S3 bucket, [contact Braintrust](mailto:support@braintrust.dev) for help.
    </Warning>

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

    This creates the ECS services, ALB, and related infrastructure. CloudFront continues to send traffic to Lambda. ECS and Lambda run side by side while ECS warms up.
  </Step>

  <Step title="Verify your data plane is healthy">
    After the apply completes, exercise the data plane with a few calls in the Braintrust UI to confirm traffic is still flowing correctly through Lambda.

    Go to **<Icon icon="settings-2" /> Settings** > [**<Icon icon="lock" /> Data plane**](https://www.braintrust.dev/app/~/configuration/org/api-url) and confirm all settings show green status.
  </Step>

  <Step title="Cut over traffic to ECS">
    Set `enable_ecs_api = true` in your module configuration and apply again:

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

      enable_ecs_api = true

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

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

    CloudFront will route API traffic to the ECS ALB instead of API Gateway and Lambda.
  </Step>

  <Step title="Verify the cutover">
    Exercise the data plane again. Run API requests, ingest traces, and run an eval to confirm traffic is flowing correctly through ECS.
  </Step>
</Steps>

## Rollback

If you need to revert to Lambda after cutting over, set `enable_ecs_api = false` and apply:

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

  enable_ecs_api = false

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

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

CloudFront will revert to the Lambda path. This rollback is available as long as the Lambdas remain deployed.

## Next steps

* [Self-hosting releases](/data-plane-changelog) — review release notes and infrastructure requirements for each data plane version
* [Advanced configuration](/admin/self-hosting/advanced) — configure telemetry, network access, rate limiting, and other options