Upgrade your deployment

Upgrading to data plane v2.0? It requires a multi-step migration with irreversible infrastructure changes. Follow the Upgrade to v2.0 guide instead.

AWS
GCP
Azure

This guide shows the routine process for upgrading the Braintrust data plane in your AWS account.

Upgrading to AWS Terraform module v6.0? It requires a two-step apply to move the API from Lambda to ECS. Follow the Upgrade to v6.0 guide instead.

How it works

On AWS, the Braintrust data plane runs on ECS and EC2 (Terraform module versions before v6.0 run the API on Lambda). The data plane version is bundled into the Terraform module — each module release pins specific versions of the Braintrust API and Brainstore in VERSIONS.json. When you update your module source to a newer version and run terraform apply, Terraform automatically deploys the corresponding data plane.To check which data plane version you’re currently running, go to Settings > Data plane in the Braintrust UI.

1. Update the module version

Check the Self-hosting releases page for your target data plane version to find the minimum Terraform module version required. Then update the ?ref= in your module source:

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

  # ... other configuration ...
}

See all module releases: GitHub Releases

2. Review and apply

As of v5.6.0, the modules/services sub-module requires the hashicorp/http provider ~> 3.3. If your .terraform.lock.hcl pins an older 3.x version, run terraform init -upgrade before terraform plan or terraform apply.

Review the planned changes before applying:

terraform plan

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.

Apply the changes:

terraform apply

This updates both the infrastructure and the data plane components in a single apply.

This guide shows the routine process for upgrading the Braintrust data plane in your GCP account.

How it works

GCP deployments have two independently upgradeable components:

Terraform module (terraform-google-braintrust-data-plane): provisions your cloud infrastructure — the GKE cluster, Cloud SQL database, Redis, and storage buckets. You upgrade this by changing the ?ref= version in your module source and running terraform apply.
Helm chart: deploys the Braintrust application (API and Brainstore containers) onto your GKE cluster. You upgrade this by running helm upgrade with a new --version.

The Helm chart --version is the chart version, not the data plane version. The data plane version is set separately via image tags in your values.yaml. Upgrading the Helm chart alone does not change which data plane version is running — you must also update the image tags.

To check which data plane version you’re currently running, go to Settings > Data plane in the Braintrust UI.

1. Decide what to upgrade

Before upgrading, check the Self-hosting releases page for your target data plane version. Each entry specifies its requirements:

“Requires: Helm X.Y.Z+” — you must upgrade the Helm chart to at least that version before or alongside updating your image tags. Update Terraform first if infrastructure changes are also listed.
No requirements listed — you can upgrade by updating image tags in values.yaml and running helm upgrade. No Terraform or chart version change needed.
Helm-only release (“No data plane version change”) — update only the Helm chart version. No image tag change needed.

2. Update infrastructure (Terraform)

Run this step when a release lists infrastructure requirements, or when you want to apply infrastructure changes independently.

terraform apply

Carefully review the output of terraform plan before applying any changes to your deployment. If you see something unexpected, like deletion of a database or storage bucket, contact Braintrust for help.

To pin to a specific Terraform module version, update the ?ref= in your module source:

module "braintrust-data-plane" {
  source = "github.com/braintrustdata/terraform-google-braintrust-data-plane?ref=vX.Y.Z"

  # ... other configuration ...
}

See all module releases: GitHub Releases

3. Update services (Helm)

Run this step to deploy a new data plane version or apply a Helm chart update.

Set the data plane version

Set the data plane version by updating the image tags for the API and Brainstore in your values.yaml. Refer to the Helm chart values reference for the exact field names.

Upgrade the Helm chart

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

Replace <chart-version> with the Helm chart version required by the release (or your current chart version if no chart upgrade is needed).

When a release requires both Terraform and Helm changes, apply Terraform first, then run the Helm upgrade.

See all Helm chart releases: GitHub Releases

This guide shows the routine process for upgrading the Braintrust data plane in your Azure account.

How it works

Azure deployments have two independently upgradeable components:

Terraform module (terraform-azure-braintrust-data-plane): provisions your cloud infrastructure — the AKS cluster, Azure Database for PostgreSQL, Redis, and storage. You upgrade this by changing the ?ref= version in your module source and running terraform apply.
Helm chart: deploys the Braintrust application (API and Brainstore containers) onto your AKS cluster. You upgrade this by running helm upgrade with a new --version.

To check which data plane version you’re currently running, go to Settings > Data plane in the Braintrust UI.

1. Decide what to upgrade

Before upgrading, check the Self-hosting releases page for your target data plane version. Each entry specifies its requirements:

“Requires: Helm X.Y.Z+” — you must upgrade the Helm chart to at least that version before or alongside updating your image tags. Update Terraform first if infrastructure changes are also listed.
No requirements listed — you can upgrade by updating image tags in values.yaml and running helm upgrade. No Terraform or chart version change needed.
Helm-only release (“No data plane version change”) — update only the Helm chart version. No image tag change needed.

2. Update infrastructure (Terraform)

Run this step when a release lists infrastructure requirements, or when you want to apply infrastructure changes independently.

terraform apply

Carefully review the output of terraform plan before applying any changes to your deployment. If you see something unexpected, like deletion of a database or storage account, contact Braintrust for help.

To pin to a specific Terraform module version, update the ?ref= in your module source:

module "braintrust-data-plane" {
  source = "github.com/braintrustdata/terraform-azure-braintrust-data-plane?ref=vX.Y.Z"

  # ... other configuration ...
}

See all module releases: GitHub Releases

Some Terraform Azure module upgrades include one-time breaking changes, such as renamed node pool variables, an azurerm provider upgrade, or a Terraform state migration. Before bumping the module across major versions, review the Terraform Azure module releases entries on the Self-hosting releases page for the versions you’re crossing.

3. Update services (Helm)

Run this step to deploy a new data plane version or apply a Helm chart update.

Set the data plane version

Set the data plane version by updating the image tags for the API and Brainstore in your values.yaml. Refer to the Helm chart values reference for the exact field names.

Upgrade the Helm chart

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

Replace <chart-version> with the Helm chart version required by the release (or your current chart version if no chart upgrade is needed).

When a release requires both Terraform and Helm changes, apply Terraform first, then run the Helm upgrade.

See all Helm chart releases: GitHub Releases

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

Start

Instrument

Observe

Annotate

Evaluate

Deploy

Admin

Best practices

Upgrade your deployment

How it works

1. Update the module version

2. Review and apply

How it works

1. Decide what to upgrade

2. Update infrastructure (Terraform)

3. Update services (Helm)

How it works

1. Decide what to upgrade

2. Update infrastructure (Terraform)

3. Update services (Helm)

Next steps

​How it works

​1. Update the module version

​2. Review and apply

​How it works

​1. Decide what to upgrade

​2. Update infrastructure (Terraform)

​3. Update services (Helm)

​How it works

​1. Decide what to upgrade

​2. Update infrastructure (Terraform)

​3. Update services (Helm)

​Next steps

How it works

1. Update the module version

2. Review and apply

How it works

1. Decide what to upgrade

2. Update infrastructure (Terraform)

3. Update services (Helm)

How it works

1. Decide what to upgrade

2. Update infrastructure (Terraform)

3. Update services (Helm)

Next steps