Skip to main content
Terraform module v6 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 the move itself does not affect the data plane version. Each v6 release pins its own data plane images, so check Self-hosting releases for the version your target release ships. Upgrade to v6.5.0 or later, not to v6.0.0. Go directly from v5.x to the latest v6 release.
On module v6.4.0 and earlier, cutting API traffic over to ECS (enable_ecs_api = true) also routes LLM calls from user-authored scorers and tools running in the quarantine environment to the Braintrust-hosted Gateway at gateway.braintrust.dev, sending that traffic outside your AWS account. Module v6.5.0 and later routes those calls through the deployment’s own AI proxy, or through your own Gateway if you run one. If you already cut over on an earlier v6 release, upgrade to v6.5.0 or later to keep that traffic in your account.
Always upgrade one major version at a time. If you are on v4.x, upgrade to v5.x first before upgrading to v6. See the routine upgrade guide for the standard process.

​
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
  • braintrust-api-background: background paths (evals, function invoke, proxy)
The module routes each path to the right service for you. For the current path assignments and the variables that size each service, see Scaling and storage. During the transition, the API Lambdas remain deployed and are kept warm. A future module release removes them.
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.

​
Upgrade steps

1

Bump the module to v6 and apply

Update your module source to a v6 release (v6.5.0 or later), leaving enable_ecs_api at its default (false):
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.
Carefully review the output of terraform plan before applying. If you see something unexpected, like deletion of a database or S3 bucket, contact Braintrust for help.
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.
2

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 Settings > Data plane and confirm all settings show green status.
3

Cut over traffic to ECS

Set enable_ecs_api = true in your module configuration and apply again:
CloudFront will route API traffic to the ECS ALB instead of API Gateway and Lambda.
4

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.

​
Rollback

If you need to revert to Lambda after cutting over, set enable_ecs_api = false and apply:
CloudFront will revert to the Lambda path. This rollback is available as long as the Lambdas remain deployed.

​
Next steps

  • Self-hosting releases — review release notes and infrastructure requirements for each data plane version.
  • Configuration — configure telemetry, network access, rate limiting, and other options.
  • Deploy the Braintrust Gateway — run the Gateway in your data plane (module v6.5.0 or later). Enabling it is independent of this cutover, so you can do either first.