Upgrade to data plane v2.x

Data plane v2.0 introduced many new features, including trace-level scorers, sandboxes for agent evals, and log indexing and full-text search. The current recommended target for the v2.x cutover is data plane v2.1.1. The module and chart versions below deploy v2.1.1 images unless noted otherwise. This guide assumes a standard Braintrust deployment using the Braintrust Terraform modules or Helm chart to manage storage, identity, networking, and generated configuration. If your deployment customizes those layers, confirm the equivalent resources, permissions, network paths, and runtime environment are in place before applying the version upgrade. Braintrust components must be able to list, read, write, and delete the generated object-storage paths, including versioned deletes where object versioning is enabled.

Avoid bundling unrelated configuration or workload changes into the upgrade window. Validate the version upgrade first, then separately ramp new automations, scoring traffic, credential rotations, or storage and network policy changes.

AWS
GCP
Azure

This guide shows the process for upgrading the Braintrust data plane to v2.x in your AWS account.

1. Prepare for v2.x

Before upgrading to data plane v2.x, you need to reach Terraform module v4.5.0 (data plane v1.1.32) and enable the efficient WAL format. v1.1.32 is the required foundation for v2.x. It ensures all Brainstore configuration is in place and verified before the upgrade.

Upgrade Terraform module

The goal of this step is to reach v4.5.0. Check your current module version in main.tf:

module "braintrust-data-plane" {
  source = "github.com/braintrustdata/terraform-aws-braintrust-data-plane?ref=v..." # your current version
}

Then follow the path for your starting point:

Starting version	Sub-steps to follow
TF module < v3.0.0	1 → 2 → 3
TF module v3.x	2 → 3
TF module v4.x (not v4.5.0)	3 only
TF module v4.5.0	Skip to Enable efficient WAL format
TF module v5.0.0, v5.1.0, or v5.2.0	Skip to Upgrade to v2.x
TF module v5.2.1+	Skip to Enable no-PostgreSQL mode

Upgrade to Terraform module v3.1.3

This upgrades the data plane from v1.1.25 to v1.1.27. There are no breaking changes.

module "braintrust-data-plane" {
  source = "github.com/braintrustdata/terraform-aws-braintrust-data-plane?ref=v3.1.3"

  # ... other configuration
}

terraform apply

Upgrade to Terraform module v4.0.0

This step upgrades the AWS provider from v5 to v6. The Terraform state file changes made in this step are irreversible. Apply at this version explicitly before proceeding, so that if anything goes wrong, it is clear whether the provider upgrade or the subsequent data plane bump caused it.

module "braintrust-data-plane" {
  source = "github.com/braintrustdata/terraform-aws-braintrust-data-plane?ref=v4.0.0"

  # ... other configuration
}

terraform apply

The data plane version does not change in this step.

For straightforward deployments, you can upgrade directly from v3.1.3 to v4.5.0, skipping the v4.0.0 stop. The intermediate stop is recommended for complex deployments to isolate the AWS provider migration. If something goes wrong in a single jump, it’s harder to identify the cause.

Upgrade to Terraform module v4.5.0

This upgrades the data plane to v1.1.32. v4.5.0 also introduces the skip_pg_for_brainstore_objects variable used in the Topics enablement step.

module "braintrust-data-plane" {
  source = "github.com/braintrustdata/terraform-aws-braintrust-data-plane?ref=v4.5.0"

  # ... other configuration
}

terraform apply

Enable efficient WAL format

This must be a separate terraform apply from the v4.5.0 upgrade. If you set brainstore_wal_footer_version in the same apply, Brainstore nodes that are still rolling out won’t be able to read the new WAL format. Wait until all nodes are confirmed running v1.1.32 before applying this step.

Add brainstore_wal_footer_version = "v1" to your module and apply:

module "braintrust-data-plane" {
  source = "github.com/braintrustdata/terraform-aws-braintrust-data-plane?ref=v4.5.0"

  brainstore_wal_footer_version = "v1"

  # ... other configuration
}

terraform apply

After applying, go to Settings > Brainstore and, under Brainstore configuration, check the WAL footer version (BRAINSTORE_WAL_FOOTER_VERSION) row. On v1.1.32, it will show “Unable to verify setting. Please upgrade to configure.” The setting is active; Brainstore v1.1.32 does not report it back to the control plane. It will show correctly after upgrading to v2.x.

This step is strongly recommended but not mechanically enforced. Deployments running mixed WAL formats become increasingly difficult to tune at scale.

Run the preflight check

Go to Settings > Brainstore. Under Brainstore configuration, verify the following expected statuses before proceeding:

Setting	Expected status
License	Configured
Telemetry	Configured
Data plane service token	Configured
Brainstore default mode (`BRAINSTORE_DEFAULT`)	Configured
Insert logs (`INSERT_LOGS2`)	Configured
Insert row references (`BRAINSTORE_INSERT_ROW_REFS`)	Configured
Realtime WAL (`BRAINSTORE_REALTIME_WAL_BUCKET`)	Configured
Ephemeral WAL (`BRAINSTORE_XACT_MANAGER_URI`)	Configured
Proxy URL (`BRAINSTORE_AI_PROXY_URL`)	Configured
Redis (`BRAINSTORE_REDIS_URI`)	Configured
Brainstore direct writes	”Upgrade to configure Brainstore direct writes”

On v1.1.32, items like WAL footer version, response cache URI, and code bundle URI are not displayed. They appear only after upgrading to v2.x. The HTTP/2 check may show a warning on v1.1.32. This resolves after upgrading.

If any of the first ten rows are not green, resolve them before proceeding. Contact Braintrust support if you need help.

2. Upgrade to v2.x

With preflight complete, upgrade to Terraform module v5.2.1, which ships the recommended data plane v2.1.1 images. The WAL footer also bumps to v3 in the same apply.

If you are already on Terraform module v5.2.1 with WAL footer version set to v3, skip to Enable no-PostgreSQL mode.

Apply the upgrade

Update your module to v5.2.1 and bump the WAL footer to v3. You can do both in the same apply. As long as WAL footer is already on v1 from the previous step, all v2.x nodes will understand the v3 format on startup.Because the latest module defaults no-PostgreSQL mode on, explicitly disable it for the base upgrade. Enable it only in the next step.

module "braintrust-data-plane" {
  source = "github.com/braintrustdata/terraform-aws-braintrust-data-plane?ref=v5.2.1"

  brainstore_wal_footer_version = "v3"
  skip_pg_for_brainstore_objects = ""

  # ... other configuration
}

terraform apply

Verify settings

Go to Settings > Brainstore and, under Brainstore configuration, verify the following are all green:

Setting	Expected status
License	Configured
Telemetry	Configured
Data plane service token	Configured
Brainstore default mode (`BRAINSTORE_DEFAULT`)	Configured
Insert logs (`INSERT_LOGS2`)	Configured
Insert row references (`BRAINSTORE_INSERT_ROW_REFS`)	Configured
Realtime WAL (`BRAINSTORE_REALTIME_WAL_BUCKET`)	Configured
Ephemeral WAL (`BRAINSTORE_XACT_MANAGER_URI`)	Configured
Proxy URL (`BRAINSTORE_AI_PROXY_URL`)	Configured
Redis (`BRAINSTORE_REDIS_URI`)	Configured
Response cache URI (`BRAINSTORE_RESPONSE_CACHE_URI`)	Configured
Code bundle URI (`BRAINSTORE_CODE_BUNDLE_URI`)	Configured
HTTP/2	Data plane is using HTTP/2 or higher

Brainstore direct writes will show “Upgrade to configure Brainstore direct writes.” This is enabled in the next step.

Validate the base upgrade

Before enabling no-PostgreSQL mode, validate the workloads your team relies on. For example, trace one production-shaped request, run an eval suite you use regularly, and invoke or iterate on a prompt. If you use online scorers or automations, trigger one through its normal online path. For trace-level scorers, choose one that uses full trace context. If these workflows round-trip cleanly through the data plane and look right in the UI, continue to no-PostgreSQL mode.

Enable no-PostgreSQL mode

No-PostgreSQL mode removes PostgreSQL from the Brainstore write path, delivering higher ingestion throughput. This step is a prerequisite for Topics but does not enable them.

The switch to no-PostgreSQL mode is one-way: Once Brainstore is writing data directly, rolling back requires downtime to drain and re-ingest. Enable it only when you are ready to commit.

Keep your module on v5.2.1 and set skip_pg_for_brainstore_objects = "all":

module "braintrust-data-plane" {
  source = "github.com/braintrustdata/terraform-aws-braintrust-data-plane?ref=v5.2.1"

  brainstore_wal_footer_version = "v3"
  skip_pg_for_brainstore_objects = "all"

  # ... other configuration
}

terraform apply

Repeat the same workload validation after enabling no-PostgreSQL mode. If the same representative workflows round-trip cleanly through the data plane and look right in the UI, proceed to the next environment.

Enable Topics

Topics for self-hosted deployments has specific deployment, inference, billing, and maintenance requirements, and Braintrust must grant access to your organization. Completing the full v2.x upgrade and no-PostgreSQL mode migration is a prerequisite, and the following conditions must also be met before Topics can be enabled:

Standard deployment required. Topics is supported on standard Terraform/Helm deployments only. Custom Kubernetes clusters using the Helm chart on non-standard infrastructure are not supported.
Braintrust-hosted inference required. Topics runs LLM calls on models hosted by Braintrust with Zero Data Retention (ZDR). Bring-your-own-model is not supported. Currently US-only.
Built-in models must be enabled. Self-hosted organizations have built-in models disabled by default, so no trace data leaves your network boundary unless you opt in. Because Topics depends on built-in models, an admin must explicitly enable them before Topics can run.
Pricing is not included by default. Topics usage is not covered by standard contracts. Discuss pricing with your account team before proceeding.
Ongoing maintenance required. Self-hosted Topics deployments run on a frequent-release build track separate from the tagged data plane versions and will require regular upgrades to receive the latest fixes and improvements.

If you meet all of these requirements and want to proceed, contact your account team or Braintrust support. Until Braintrust enables Topics access for your organization, the Topics page and Topics automations remain blocked, even after the upgrade and no-PostgreSQL migration are complete.

Configuration reference

Core configuration (auto-set by v4.4.0)

Variable	Source	Since
`SERVICE_TOKEN_SECRET_KEY`	Auto-generated 32-character key in Secrets Manager	v3.0.0
`BRAINSTORE_REDIS_URI`	ElastiCache endpoint and port	v3.1.0
`BRAINSTORE_DEFAULT`	Hardcoded `"force"`	v3.0.0
`INSERT_LOGS2`	Hardcoded `"true"`	v3.0.0
`BRAINSTORE_INSERT_ROW_REFS`	Hardcoded `"true"`	v3.0.0
`BRAINSTORE_REALTIME_WAL_BUCKET`	Auto-created S3 bucket	v3.0.0
`BRAINSTORE_AI_PROXY_URL`	Fetched from SSM at boot	v4.0.3
`BRAINSTORE_XACT_MANAGER_URI`	Same ElastiCache endpoint as Redis	v4.4.0
`BRAINSTORE_RESPONSE_CACHE_URI`	Module-created S3 bucket (at `/brainstore-cache` prefix)	v4.4.0
`BRAINSTORE_CODE_BUNDLE_URI`	Module-created S3 bucket	v4.4.0

WAL footer version (requires explicit configuration)

Variable	How to set	Since
`BRAINSTORE_WAL_FOOTER_VERSION`	Set `brainstore_wal_footer_version = "v1"` in module	v4.5.0

Allowed values: "" (disabled, default), "v1", "v2", "v3". Set to "v1" as part of the pre-upgrade steps. Only set to "v3" after successfully deploying v2.x.

No-PostgreSQL mode (opt-in, post-upgrade)

Variable	How to set	Since
`SKIP_PG_FOR_BRAINSTORE_OBJECTS`	Set `skip_pg_for_brainstore_objects` in module	v4.5.0
`BRAINSTORE_ASYNC_SCORING_OBJECTS`	Auto-derived from `skip_pg_for_brainstore_objects`	v4.5.0
`BRAINSTORE_LOG_AUTOMATIONS_OBJECTS`	Auto-derived from `skip_pg_for_brainstore_objects`	v4.5.0
`BRAINSTORE_WAL_USE_EFFICIENT_FORMAT`	Auto-enabled when either `brainstore_wal_footer_version` or `skip_pg_for_brainstore_objects` is set	v4.5.0

Setting skip_pg_for_brainstore_objects = "all" is a prerequisite for enabling Topics. The module automatically fans this value out to BRAINSTORE_ASYNC_SCORING_OBJECTS and BRAINSTORE_LOG_AUTOMATIONS_OBJECTS.

This guide shows the process for upgrading the Braintrust data plane to v2.x in your GCP account.

1. Prepare for v2.x

Before upgrading to data plane v2.x, you need to reach Helm chart v5.0.1 (data plane v1.1.32) and enable the efficient WAL format. v1.1.32 is the required foundation for v2.x. It ensures all Brainstore configuration is in place and verified before the upgrade.

Upgrade Helm chart

Check your current Helm chart version:

helm list -n braintrust

Then follow the path for your starting point:

Starting version	Sub-steps to follow
Helm chart < v3.1.1	1 → 2 → 3
Helm chart v3.x	2 → 3
Helm chart v4.x	3 only
Helm chart v5.0.1	Skip to Enable efficient WAL format
Helm chart v6.0.0, v6.1.0, or v6.2.0	Skip to Upgrade to v2.x
Helm chart v6.2.1+	Skip to Enable no-PostgreSQL mode

Upgrade to Helm chart v3.1.1

This upgrades the data plane from v1.1.27 to v1.1.31. There are no breaking changes.

helm upgrade braintrust \
  oci://public.ecr.aws/braintrust/helm/braintrust \
  --namespace braintrust \
  --version 3.1.1 \
  --values helm-values.yaml

After applying, restart pods:

kubectl rollout restart deployment -n braintrust

Upgrade to Helm chart v4.0.0

This step upgrades the data plane to v1.1.32 and introduces bidirectional communication between Brainstore and API pods. Brainstore now needs to reach the API pods. The chart auto-sets BRAINSTORE_AI_PROXY_URL to http://braintrust-api:8000.

If your cluster has network policies or security rules restricting traffic between pods, allow Brainstore pods to reach the API service on port 8000 before upgrading.

helm upgrade braintrust \
  oci://public.ecr.aws/braintrust/helm/braintrust \
  --namespace braintrust \
  --version 4.0.0 \
  --values helm-values.yaml

After applying, restart pods:

kubectl rollout restart deployment -n braintrust

Upgrade to Helm chart v5.0.1

This step enables fast readers, isolated Brainstore nodes that handle common UI queries. Fast readers are enabled by default with 2 replicas and use the same node spec as standard readers, increasing your cluster node count by 2. You can upgrade directly to v5.0.1 from any v4.x version.

Before upgrading, account for 2 additional fast reader nodes in your cluster capacity. If you have customized brainstore.reader settings in values.yaml, mirror those customizations to the new brainstore.fastreader block. See Configure Brainstore fast readers for details.

helm upgrade braintrust \
  oci://public.ecr.aws/braintrust/helm/braintrust \
  --namespace braintrust \
  --version 5.0.1 \
  --values helm-values.yaml

After applying, restart pods:

kubectl rollout restart deployment -n braintrust

Enable efficient WAL format

This must be a separate helm upgrade after confirming all pods are running v1.1.32. Setting this during the same upgrade as the version bump risks Brainstore nodes still rolling out being unable to read the new WAL format.

Set brainstoreWalFooterVersion in your helm-values.yaml:

brainstoreWalFooterVersion: "v1"

Then apply:

helm upgrade braintrust \
  oci://public.ecr.aws/braintrust/helm/braintrust \
  --namespace braintrust \
  --version 5.1.0 \
  --values helm-values.yaml

On chart v5.1.0+, pods will automatically restart after applying the upgrade.Once the pods have cycled, go to Settings > Brainstore and, under Brainstore configuration, check the WAL footer version (BRAINSTORE_WAL_FOOTER_VERSION) row. On v1.1.32, it will show “Unable to verify setting. Please upgrade to configure.” The setting is active; Brainstore v1.1.32 does not report it back to the control plane. It will show correctly after upgrading to v2.x.

This step is strongly recommended but not mechanically enforced. Deployments running mixed WAL formats become increasingly difficult to tune at scale.

Run the preflight check

Go to Settings > Brainstore. Under Brainstore configuration, verify the following expected statuses before proceeding:

Setting	Expected status
License	Configured
Telemetry	Configured
Data plane service token	Configured
Brainstore default mode (`BRAINSTORE_DEFAULT`)	Configured
Insert logs (`INSERT_LOGS2`)	Configured
Insert row references (`BRAINSTORE_INSERT_ROW_REFS`)	Configured
Realtime WAL (`BRAINSTORE_REALTIME_WAL_BUCKET`)	Configured
Ephemeral WAL (`BRAINSTORE_XACT_MANAGER_URI`)	Configured
Proxy URL (`BRAINSTORE_AI_PROXY_URL`)	Configured
Redis (`BRAINSTORE_REDIS_URI`)	Configured
Brainstore direct writes	”Upgrade to configure Brainstore direct writes”

If any of the first ten rows are not green, resolve them before proceeding. Contact Braintrust support if you need help.

Update Workload Identity bindings

Data plane v2.0 introduces API pod endpoints that access GCS directly. Prior versions only accessed GCS from Brainstore pods. The GCP IAM binding must be updated to grant the braintrust-api Kubernetes service account Workload Identity access before upgrading.

If using the Braintrust GCP Terraform module, update to v1.5.2 and run terraform apply before upgrading Helm to v6.2.1. The updated module includes the binding for both the brainstore and braintrust-api service accounts.
module "braintrust-data-plane" { source = "github.com/braintrustdata/terraform-google-braintrust-data-plane?ref=v1.5.2" # ... other configuration }
terraform apply

If managing IAM manually, add the binding:

gcloud iam service-accounts add-iam-policy-binding \
  <brainstore-gcp-service-account>@<project>.iam.gserviceaccount.com \
  --role roles/iam.workloadIdentityUser \
  --member "serviceAccount:<project>.svc.id.goog[<namespace>/braintrust-api]"

Apply these IAM changes before upgrading to v2.x. Without this binding, the API pod will return errors on endpoints that access GCS directly.

2. Upgrade to v2.x

With preflight complete, upgrade to Helm chart v6.2.1, which ships the recommended data plane v2.1.1 images. The WAL footer also bumps to v3 in the same apply.

If you are already on Helm chart v6.2.1 with WAL footer version set to v3, skip to Enable no-PostgreSQL mode.

Apply the upgrade

Update your helm-values.yaml to bump the WAL footer to v3. Because the latest chart defaults no-PostgreSQL mode on, explicitly disable it for the base upgrade. Enable it only in the next step.

brainstoreWalFooterVersion: "v3"
skipPgForBrainstoreObjects: ""

Breaking change: Chart v6.2.1 disables code function execution by default. To preserve code-backed scorers, tools, or functions on a single-org deployment, add:

api:
  allowCodeFunctionExecution: true

If your deployment uses ORG_NAME=* or hosts multiple Braintrust organizations, contact Braintrust before enabling code function execution.

Apply Helm chart v6.2.1:

helm upgrade braintrust \
  oci://public.ecr.aws/braintrust/helm/braintrust \
  --namespace braintrust \
  --version 6.2.1 \
  --values helm-values.yaml

Pods will automatically restart after applying the upgrade.

Verify settings

After the pods have cycled, go to Settings > Brainstore and, under Brainstore configuration, verify the following are all green:

Setting	Expected status
License	Configured
Telemetry	Configured
Data plane service token	Configured
Brainstore default mode (`BRAINSTORE_DEFAULT`)	Configured
Insert logs (`INSERT_LOGS2`)	Configured
Insert row references (`BRAINSTORE_INSERT_ROW_REFS`)	Configured
Realtime WAL (`BRAINSTORE_REALTIME_WAL_BUCKET`)	Configured
Ephemeral WAL (`BRAINSTORE_XACT_MANAGER_URI`)	Configured
Proxy URL (`BRAINSTORE_AI_PROXY_URL`)	Configured
Redis (`BRAINSTORE_REDIS_URI`)	Configured
Response cache URI (`BRAINSTORE_RESPONSE_CACHE_URI`)	Configured
Code bundle URI (`BRAINSTORE_CODE_BUNDLE_URI`)	Configured
HTTP/2	Data plane is using HTTP/2 or higher

Brainstore direct writes will show “Upgrade to configure Brainstore direct writes.” This is enabled in the next step.

Validate the base upgrade

Enable no-PostgreSQL mode

No-PostgreSQL mode removes PostgreSQL from the Brainstore write path, delivering higher ingestion throughput. This step is a prerequisite for Topics but does not enable them.

The switch to no-PostgreSQL mode is one-way: Once Brainstore is writing data directly, rolling back requires downtime to drain and re-ingest. Enable it only when you are ready to commit.

Set skipPgForBrainstoreObjects in your helm-values.yaml:

skipPgForBrainstoreObjects: "all"

Keep Helm chart v6.2.1 and apply the updated values:

helm upgrade braintrust \
  oci://public.ecr.aws/braintrust/helm/braintrust \
  --namespace braintrust \
  --version 6.2.1 \
  --values helm-values.yaml

Then repeat the same workload validation after enabling no-PostgreSQL mode. If the same representative workflows round-trip cleanly through the data plane and look right in the UI, proceed to the next environment.

Enable Topics

Standard deployment required. Topics is supported on standard Terraform/Helm deployments only. Custom Kubernetes clusters using the Helm chart on non-standard infrastructure are not supported.
Braintrust-hosted inference required. Topics runs LLM calls on models hosted by Braintrust with Zero Data Retention (ZDR). Bring-your-own-model is not supported. Currently US-only.
Built-in models must be enabled. Self-hosted organizations have built-in models disabled by default, so no trace data leaves your network boundary unless you opt in. Because Topics depends on built-in models, an admin must explicitly enable them before Topics can run.
Pricing is not included by default. Topics usage is not covered by standard contracts. Discuss pricing with your account team before proceeding.
Ongoing maintenance required. Self-hosted Topics deployments run on a frequent-release build track separate from the tagged data plane versions and will require regular upgrades to receive the latest fixes and improvements.

Configuration reference

Core configuration (auto-set by Helm v5.1.0)

Variable	Source	Pods
`BRAINSTORE_REDIS_URI`	From `REDIS_URL` secret	reader, writer, fastreader
`BRAINSTORE_DEFAULT`	Hardcoded `"force"`	API
`INSERT_LOGS2`	Hardcoded `"true"`	API
`BRAINSTORE_INSERT_ROW_REFS`	Hardcoded `"true"`	API
`BRAINSTORE_REALTIME_WAL_BUCKET`	From `objectStorage` values	API
`BRAINSTORE_AI_PROXY_URL`	Built from `api.name` and `api.service.port`	reader, writer, fastreader
`BRAINSTORE_XACT_MANAGER_URI`	From `REDIS_URL` secret	reader, writer, fastreader
`BRAINSTORE_RESPONSE_CACHE_URI`	Auto-derived from `objectStorage` config	reader, writer, fastreader
`BRAINSTORE_CODE_BUNDLE_URI`	Auto-derived from `objectStorage` config	reader, writer, fastreader

WAL footer version (requires explicit configuration)

Variable	How to set	Since	Pods
`BRAINSTORE_WAL_FOOTER_VERSION`	Set `brainstoreWalFooterVersion` in `helm-values.yaml`	v5.1.0	API
`BRAINSTORE_WAL_USE_EFFICIENT_FORMAT`	Auto-enabled when either `brainstoreWalFooterVersion` or `skipPgForBrainstoreObjects` is set	v5.1.0	API

Set brainstoreWalFooterVersion: "v1" as part of the pre-upgrade steps. Only set to "v3" after successfully deploying v2.x.

No-PostgreSQL mode (opt-in, post-upgrade)

Variable	How to set	Since	Pods
`SKIP_PG_FOR_BRAINSTORE_OBJECTS`	Set `skipPgForBrainstoreObjects` in `helm-values.yaml`	v5.1.0	API
`BRAINSTORE_ASYNC_SCORING_OBJECTS`	Auto-derived from `skipPgForBrainstoreObjects`	v5.1.0	reader, writer, fastreader
`BRAINSTORE_LOG_AUTOMATIONS_OBJECTS`	Auto-derived from `skipPgForBrainstoreObjects`	v5.1.0	reader, writer, fastreader

Setting skipPgForBrainstoreObjects: "all" is a prerequisite for enabling Topics. The chart automatically fans this value out to BRAINSTORE_ASYNC_SCORING_OBJECTS and BRAINSTORE_LOG_AUTOMATIONS_OBJECTS.

This guide shows the process for upgrading the Braintrust data plane to v2.x in your Azure account.

1. Prepare for v2.x

Upgrade Helm chart

Check your current Helm chart version:

helm list -n braintrust

Then follow the path for your starting point:

Starting version	Sub-steps to follow
Helm chart < v3.1.1	1 → 2 → 3
Helm chart v3.x	2 → 3
Helm chart v4.x	3 only
Helm chart v5.0.1	Skip to Enable efficient WAL format
Helm chart v6.0.0, v6.1.0, or v6.2.0	Skip to Upgrade to v2.x
Helm chart v6.2.1+	Skip to Enable no-PostgreSQL mode

Upgrade to Helm chart v3.1.1

This upgrades the data plane from v1.1.27 to v1.1.31. There are no breaking changes.

helm upgrade braintrust \
  oci://public.ecr.aws/braintrust/helm/braintrust \
  --namespace braintrust \
  --version 3.1.1 \
  --values helm-values.yaml

After applying, restart pods:

kubectl rollout restart deployment -n braintrust

Upgrade to Helm chart v4.0.0

If your cluster has network policies or security rules restricting traffic between pods, allow Brainstore pods to reach the API service on port 8000 before upgrading.

helm upgrade braintrust \
  oci://public.ecr.aws/braintrust/helm/braintrust \
  --namespace braintrust \
  --version 4.0.0 \
  --values helm-values.yaml

After applying, restart pods:

kubectl rollout restart deployment -n braintrust

Upgrade to Helm chart v5.0.1

helm upgrade braintrust \
  oci://public.ecr.aws/braintrust/helm/braintrust \
  --namespace braintrust \
  --version 5.0.1 \
  --values helm-values.yaml

After applying, restart pods:

kubectl rollout restart deployment -n braintrust

Enable efficient WAL format

Set brainstoreWalFooterVersion in your helm-values.yaml:

brainstoreWalFooterVersion: "v1"

Then apply:

helm upgrade braintrust \
  oci://public.ecr.aws/braintrust/helm/braintrust \
  --namespace braintrust \
  --version 5.1.0 \
  --values helm-values.yaml

This step is strongly recommended but not mechanically enforced. Deployments running mixed WAL formats become increasingly difficult to tune at scale.

Run the preflight check

Go to Settings > Brainstore. Under Brainstore configuration, verify the following expected statuses before proceeding:

Setting	Expected status
License	Configured
Telemetry	Configured
Data plane service token	Configured
Brainstore default mode (`BRAINSTORE_DEFAULT`)	Configured
Insert logs (`INSERT_LOGS2`)	Configured
Insert row references (`BRAINSTORE_INSERT_ROW_REFS`)	Configured
Realtime WAL (`BRAINSTORE_REALTIME_WAL_BUCKET`)	Configured
Ephemeral WAL (`BRAINSTORE_XACT_MANAGER_URI`)	Configured
Proxy URL (`BRAINSTORE_AI_PROXY_URL`)	Configured
Redis (`BRAINSTORE_REDIS_URI`)	Configured
Brainstore direct writes	”Upgrade to configure Brainstore direct writes”

If any of the first ten rows are not green, resolve them before proceeding. Contact Braintrust support if you need help.

Update Terraform module

Update the Braintrust Azure Terraform module to v1.1.0 and apply before upgrading Helm to v6.2.1:

module "braintrust-data-plane" {
  source = "github.com/braintrustdata/terraform-azure-braintrust-data-plane?ref=v1.1.0"

  # ... other configuration
}

terraform apply

2. Upgrade to v2.x

With preflight complete, upgrade to Helm chart v6.2.1, which ships the recommended data plane v2.1.1 images. The WAL footer also bumps to v3 in the same apply.

If you are already on Helm chart v6.2.1 with WAL footer version set to v3, skip to Enable no-PostgreSQL mode.

Apply the upgrade

Update your helm-values.yaml to bump the WAL footer to v3. Because the latest chart defaults no-PostgreSQL mode on, explicitly disable it for the base upgrade. Enable it only in the next step.

brainstoreWalFooterVersion: "v3"
skipPgForBrainstoreObjects: ""

Breaking change: Chart v6.2.1 disables code function execution by default. To preserve code-backed scorers, tools, or functions on a single-org deployment, add:

api:
  allowCodeFunctionExecution: true

If your deployment uses ORG_NAME=* or hosts multiple Braintrust organizations, contact Braintrust before enabling code function execution.

Then apply Helm chart v6.2.1:

helm upgrade braintrust \
  oci://public.ecr.aws/braintrust/helm/braintrust \
  --namespace braintrust \
  --version 6.2.1 \
  --values helm-values.yaml

Pods will automatically restart after applying the upgrade.

Verify settings

After the pods have cycled, go to Settings > Brainstore and, under Brainstore configuration, verify the following are all green:

Setting	Expected status
License	Configured
Telemetry	Configured
Data plane service token	Configured
Brainstore default mode (`BRAINSTORE_DEFAULT`)	Configured
Insert logs (`INSERT_LOGS2`)	Configured
Insert row references (`BRAINSTORE_INSERT_ROW_REFS`)	Configured
Realtime WAL (`BRAINSTORE_REALTIME_WAL_BUCKET`)	Configured
Ephemeral WAL (`BRAINSTORE_XACT_MANAGER_URI`)	Configured
Proxy URL (`BRAINSTORE_AI_PROXY_URL`)	Configured
Redis (`BRAINSTORE_REDIS_URI`)	Configured
Response cache URI (`BRAINSTORE_RESPONSE_CACHE_URI`)	Configured
Code bundle URI (`BRAINSTORE_CODE_BUNDLE_URI`)	Configured
HTTP/2	Data plane is using HTTP/2 or higher

Brainstore direct writes will show “Upgrade to configure Brainstore direct writes.” This is enabled in the next step.

Validate the base upgrade

Enable no-PostgreSQL mode

No-PostgreSQL mode removes PostgreSQL from the Brainstore write path, delivering higher ingestion throughput. This step is a prerequisite for Topics but does not enable them.

The switch to no-PostgreSQL mode is one-way: Once Brainstore is writing data directly, rolling back requires downtime to drain and re-ingest. Enable it only when you are ready to commit.

Set skipPgForBrainstoreObjects in your helm-values.yaml:

skipPgForBrainstoreObjects: "all"

Keep Helm chart v6.2.1 and apply the updated values:

helm upgrade braintrust \
  oci://public.ecr.aws/braintrust/helm/braintrust \
  --namespace braintrust \
  --version 6.2.1 \
  --values helm-values.yaml

Enable Topics

Standard deployment required. Topics is supported on standard Terraform/Helm deployments only. Custom Kubernetes clusters using the Helm chart on non-standard infrastructure are not supported.
Braintrust-hosted inference required. Topics runs LLM calls on models hosted by Braintrust with Zero Data Retention (ZDR). Bring-your-own-model is not supported. Currently US-only.
Built-in models must be enabled. Self-hosted organizations have built-in models disabled by default, so no trace data leaves your network boundary unless you opt in. Because Topics depends on built-in models, an admin must explicitly enable them before Topics can run.
Pricing is not included by default. Topics usage is not covered by standard contracts. Discuss pricing with your account team before proceeding.
Ongoing maintenance required. Self-hosted Topics deployments run on a frequent-release build track separate from the tagged data plane versions and will require regular upgrades to receive the latest fixes and improvements.

Configuration reference

Core configuration (auto-set by Helm v5.1.0)

Variable	Source	Pods
`BRAINSTORE_REDIS_URI`	From `REDIS_URL` secret	reader, writer, fastreader
`BRAINSTORE_DEFAULT`	Hardcoded `"force"`	API
`INSERT_LOGS2`	Hardcoded `"true"`	API
`BRAINSTORE_INSERT_ROW_REFS`	Hardcoded `"true"`	API
`BRAINSTORE_REALTIME_WAL_BUCKET`	From `objectStorage` values	API
`BRAINSTORE_AI_PROXY_URL`	Built from `api.name` and `api.service.port`	reader, writer, fastreader
`BRAINSTORE_XACT_MANAGER_URI`	From `REDIS_URL` secret	reader, writer, fastreader
`BRAINSTORE_RESPONSE_CACHE_URI`	Auto-derived from `objectStorage` config	reader, writer, fastreader
`BRAINSTORE_CODE_BUNDLE_URI`	Auto-derived from `objectStorage` config	reader, writer, fastreader

WAL footer version (requires explicit configuration)

Variable	How to set	Since	Pods
`BRAINSTORE_WAL_FOOTER_VERSION`	Set `brainstoreWalFooterVersion` in `helm-values.yaml`	v5.1.0	API
`BRAINSTORE_WAL_USE_EFFICIENT_FORMAT`	Auto-enabled when either `brainstoreWalFooterVersion` or `skipPgForBrainstoreObjects` is set	v5.1.0	API

Set brainstoreWalFooterVersion: "v1" as part of the pre-upgrade steps. Only set to "v3" after successfully deploying v2.x.

No-PostgreSQL mode (opt-in, post-upgrade)

Variable	How to set	Since	Pods
`SKIP_PG_FOR_BRAINSTORE_OBJECTS`	Set `skipPgForBrainstoreObjects` in `helm-values.yaml`	v5.1.0	API
`BRAINSTORE_ASYNC_SCORING_OBJECTS`	Auto-derived from `skipPgForBrainstoreObjects`	v5.1.0	reader, writer, fastreader
`BRAINSTORE_LOG_AUTOMATIONS_OBJECTS`	Auto-derived from `skipPgForBrainstoreObjects`	v5.1.0	reader, writer, fastreader

Next steps

Self-hosting releases: release notes and infrastructure requirements for each data plane version
Configuration: telemetry, network access, rate limiting, and other options

​1. Prepare for v2.x

​Upgrade Terraform module

​Enable efficient WAL format

​Run the preflight check

​2. Upgrade to v2.x

​Apply the upgrade

​Verify settings

​Validate the base upgrade

​Enable no-PostgreSQL mode

​Enable Topics

​Configuration reference

​1. Prepare for v2.x

​Upgrade Helm chart

​Enable efficient WAL format

​Run the preflight check

​Update Workload Identity bindings

​2. Upgrade to v2.x

​Apply the upgrade

​Verify settings

​Validate the base upgrade

​Enable no-PostgreSQL mode

​Enable Topics

​Configuration reference

​1. Prepare for v2.x

​Upgrade Helm chart

​Enable efficient WAL format

​Run the preflight check

​Update Terraform module

​2. Upgrade to v2.x

​Apply the upgrade

​Verify settings

​Validate the base upgrade

​Enable no-PostgreSQL mode

​Enable Topics

​Configuration reference

​Next steps

1. Prepare for v2.x

Upgrade Terraform module

Enable efficient WAL format

Run the preflight check

2. Upgrade to v2.x

Apply the upgrade

Verify settings

Validate the base upgrade

Enable no-PostgreSQL mode

Enable Topics

Configuration reference

1. Prepare for v2.x

Upgrade Helm chart

Enable efficient WAL format

Run the preflight check

Update Workload Identity bindings

2. Upgrade to v2.x

Apply the upgrade

Verify settings

Validate the base upgrade

Enable no-PostgreSQL mode

Enable Topics

Configuration reference

1. Prepare for v2.x

Upgrade Helm chart

Enable efficient WAL format

Run the preflight check

Update Terraform module

2. Upgrade to v2.x

Apply the upgrade

Verify settings

Validate the base upgrade

Enable no-PostgreSQL mode

Enable Topics

Configuration reference

Next steps