Braintrust Terraform Module

For the latest guidance, always refer to the official Braintrust documentation:

• Self-hosting overview
• Upgrade your deployment
• Data Plane 2.0 upgrade guide

This module is used to create the VPC, Databases, Lambdas, and associated resources for the self-hosted Braintrust data plane.

Major versions

Always upgrade one major version at a time. For example, go from v4 → v5 → v6. Do not jump from v4 directly to v6.

Each major version may include required configuration changes or a multi-step apply sequence. Follow the migration guide for the version you are upgrading to before applying, and review the routine upgrade guide for the general process of updating the module version and applying changes.

• Migrating from v5 to v6

How to use this module

To use this module, copy the examples/braintrust-data-plane directory to a new Terraform directory in your own repository. Follow the instructions in the README.md file in that directory to configure the module for your environment.

The default configuration is a large production-sized deployment. Please consider that when testing and adjust the configuration to use smaller sized resources.

If you're using a brand new AWS account for your Braintrust data plane you will need to run ./scripts/create-service-linked-roles.sh once to ensure IAM service-linked roles are created.

Module Configuration

All module input variables and outputs are documented inline in the module's Terraform files (see variables.tf, outputs.tf, and the submodules for details).

Organization access configuration

Prefer ID-based organization access for new deployments:

primary_org_name = "your-org-name"
allowed_org_ids  = "00000000-0000-4000-8000-000000000001,00000000-0000-4000-8000-000000000002"

allowed_org_ids is a comma-separated list of Braintrust Org IDs, not org names. Do not include spaces. You can find an org ID by hovering over the org name in the Braintrust UI. If you keep braintrust_org_name set to a specific org name for compatibility, that org is allowed by name today; include its Braintrust Org ID in allowed_org_ids for forward compatibility. braintrust_org_name remains supported for compatibility, but Braintrust plans to move toward ID-based configuration.

BTQL audit logging

BTQL query.read audit logging is disabled by default. Enable it for specific Braintrust Org IDs with either strict or best-effort mode. The two modes are mutually exclusive.

# Strict mode
btql_audit_logs_strict_org_ids = ["00000000-0000-4000-8000-000000000001"]

# Or best-effort mode
btql_audit_logs_best_effort_org_ids = ["00000000-0000-4000-8000-000000000001"]

Strict mode writes audit rows before returning query results. Best-effort mode writes audit rows asynchronously and logs failures.

Useful scripts

dump-logs.sh

This script will dump the logs for the given deployment and services to the logs-<deployment_name> directory. This is useful for debugging issues with the data plane and sharing with the Braintrust team.

# ./scripts/dump-logs.sh <deployment_name> [--minutes N] [--service <svc1,svc2,...|all>]

./scripts/dump-logs.sh bt-sandbox
Fetching logs for the last 60 minutes for APIHandler...
Fetching logs for the last 60 minutes for braintrust-api...
Fetching logs for the last 60 minutes for braintrust-api-ingest...
Fetching logs for the last 60 minutes for braintrust-api-background...
Fetching logs for the last 60 minutes for brainstore...
✅ Saved logs for brainstore to logs-bt-sandbox/brainstore.log
✅ Saved logs for braintrust-api to logs-bt-sandbox/braintrust-api.log
✅ Saved logs for braintrust-api-ingest to logs-bt-sandbox/braintrust-api-ingest.log
✅ Saved logs for braintrust-api-background to logs-bt-sandbox/braintrust-api-background.log
✅ Saved logs for APIHandler to logs-bt-sandbox/APIHandler.log

create-service-linked-roles.sh

Required for new AWS accounts to ensure IAM service-linked roles are created.

./scripts/create-service-linked-roles.sh

VPCs

This module creates two VPCs by default:

• main VPC: This is the main VPC that contains the Braintrust services.
• quarantine VPC: This is a "quarantine" VPC where user defined functions run in an isolated environment. The Braintrust API server spawns lambda functions in this VPC.

Tagging and Naming

If you have requirements to add custom tags to resources created by the module, you can do so by setting the default_tags variable on the AWS provider. The example directory examples/braintrust-data-plane shows how to do this.

Example:

provider "aws" {
  default_tags {
    tags = {
      YourCustomTag = "<your-custom-value>"
    }
  }
}

The deployment_name variable is also used to prefix the names of the resources created by the module wherever possible. It will also be applied as a tag named BraintrustDeploymentName to all resources created by the module.

CloudFront Access Logging

If you need to enable CloudFront standard access logging, you can configure it independently by referencing the cloudfront_distribution_arn output from the module. This approach gives you full flexibility over the logging configuration without requiring changes to the module itself.

See the examples/cloudfront-logging directory for a complete example showing how to set up V2 logging to S3.

Using an Existing VPC

The module supports using an existing VPC instead of creating a new dedicated one for the Braintrust services. This is useful when you want to integrate Braintrust into your existing network infrastructure.

The passed in VPC must have the following resources:

• At least 3 private subnets in different availability zones
• At least 1 public subnet
• Internet gateway and NAT gateway with proper route tables configured for private subnets

Important note: The module will still create and manage security groups for the services.

To use an existing VPC, set create_vpc = false and provide the required VPC details:

module "braintrust-data-plane" {
  source = "github.com/braintrustdata/terraform-braintrust-data-plane"

  # ... your existing configuration ...

  # Use existing VPC
  create_vpc = false
  existing_vpc_id                        = "vpc-xxxxxxxxx"
  existing_private_subnet_1_id           = "subnet-xxxxxxxxx"
  existing_private_subnet_2_id           = "subnet-yyyyyyyyy"
  existing_private_subnet_3_id           = "subnet-zzzzzzzzz"
  existing_public_subnet_1_id            = "subnet-aaaaaaaaa"
}

Development Setup

This section is only relevant if you are a contributor who wants to make changes to this module. All others can skip this section.

1. Clone the repository
2. Install mise:

curl https://mise.run | sh
echo 'eval "$(mise activate zsh)"' >> "~/.zshrc"
echo 'eval "$(mise activate zsh --shims)"' >> ~/.zprofile
exec $SHELL

3. Run mise install to install required tools
4. Run mise run setup to install pre-commit hooks