Skip to main content
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.
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 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 (/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.
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.0 and apply

Update your module source to v6.0.0, 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