> ## Documentation Index
> Fetch the complete documentation index at: https://docs.braintrust.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Upgrade your deployment

> Upgrade a self-hosted Braintrust data plane on AWS, GCP, or Azure

> [!NOTE]
>
> Upgrading to data plane v2.0? It requires a multi-step migration with irreversible infrastructure changes. Follow the [Upgrade to v2.0](https://docs.braintrust.dev/admin/self-hosting/upgrade/v2.md) guide instead.

> [tab] AWS
>
> This guide shows the routine process for upgrading the Braintrust data plane in your AWS account.
>
> > [!NOTE]
> >
> > Upgrading from AWS Terraform module v5.x to v6? It requires a two-step apply to move the API from Lambda to ECS. Follow the [Upgrade to v6](https://docs.braintrust.dev/admin/self-hosting/upgrade/v6.md) guide instead.
> >
> > Upgrading from v6 to v7 changes the defaults for API routing and the Braintrust Gateway. Follow the [Upgrade to v7](https://docs.braintrust.dev/admin/self-hosting/upgrade/v7.md) 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\*\*](https://www.braintrust.dev/app/~/configuration/data-plane) in the Braintrust UI.
>
> ## 1. Update the module version
>
> Check the [Self-hosting releases](https://docs.braintrust.dev/data-plane-changelog.md) page for your target data plane version to find the minimum Terraform module version required. Then update the `?ref=` in your module source:
>
> ```hcl theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> module "braintrust-data-plane" {
>   source = "github.com/braintrustdata/terraform-aws-braintrust-data-plane?ref=vX.Y.Z"
>
>   # ... other configuration ...
> }
> ```
>
> See all module releases: [GitHub Releases](https://github.com/braintrustdata/terraform-aws-braintrust-data-plane/releases)
>
> > [!WARNING]
> >
> > Before you apply, review these version-specific changes. Each row applies when its condition matches your deployment.
>
> | Version | Applies if | Before you apply |
> | - | - | - |
> | v6.2.0 | An SCP or IAM policy restricts tag keys | Allow the `aws-apn-id` tag key, or the upgrade fails. The module adds this tag to every resource. See [Use custom tags](https://docs.braintrust.dev/admin/self-hosting/deploy.md#use-custom-tags). |
> | v6.5.0 | The API runs on [ECS](https://docs.braintrust.dev/admin/self-hosting/upgrade/v6.md) (`enable_ecs_api = true`) | Upgrade to v6.5.0 or later. On v6.4.0 and earlier, running the API on ECS also sends LLM calls from user-authored scorers and tools to the Braintrust-hosted Gateway, outside your AWS account. |
> | v6.7.0 | Your configuration sets `enable_brainstore` | Delete the line, or the plan fails with an unsupported argument error. Brainstore is always enabled. |
> | v6.9.0 | The identity that runs Terraform uses a scoped IAM policy | Grant `lambda:InvokeFunction` on the `<deployment_name>-BrainstoreDeployment` function, which the apply invokes. |
> | v6.10.0 | Your configuration sets `loop_runtime_sandbox_egress_mode = "internet"` | Delete the line or set it to `"restricted"`, or the plan fails. Sandbox internet egress is removed. See [Sandbox egress](https://docs.braintrust.dev/admin/self-hosting/configure/loop-runtime.md#sandbox-egress). |
> | v6.10.0 | Your configuration sets `loop_runtime_version_override` to a version earlier than v2.16.0 | Remove the override or set it to v2.16.0 or later. The module doesn't check the version, and earlier Loop runtime versions don't serve the [sandbox egress gateway](https://docs.braintrust.dev/admin/self-hosting/configure/loop-runtime.md#sandbox-egress). |
> | v6.10.0 | Your `.terraform.lock.hcl` pins AWS provider v6.69.0 or later | Run `terraform init -upgrade`. The module requires an AWS provider earlier than v6.69.0, so `terraform init` fails with the existing lock file. |
>
> ## 2. Review and apply
>
> > [!NOTE]
> >
> > 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:
>
> ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> terraform plan
> ```
>
> > [!WARNING]
> >
> > If the plan deletes or replaces a database, S3 bucket, or other resource you didn't expect, don't apply it. Applying it can cause data loss. [Contact Braintrust](mailto:support@braintrust.dev) for help.
>
> > [!WARNING]
> >
> > Some module versions move resources to new Terraform addresses, so downgrading past them can destroy and recreate those resources. Review the plan before any rollback:
> >
> > * **v6.8.0**: API ECS listener rules, which can disrupt traffic. See the [v6.8.0 release notes](https://docs.braintrust.dev/data-plane-changelog.md#terraform-aws-module-releases).
> > * **v6.9.0**: The Loop runtime's database, Redis, Brainstore, and Gateway ingress rules, if your deployment runs the [Loop runtime](https://docs.braintrust.dev/admin/self-hosting/configure/loop-runtime.md).
>
> Apply the changes:
>
> ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> terraform apply
> ```
>
> This updates both the infrastructure and the data plane components in a single apply.
>
> On module v6.9.0 and later, the apply waits for the Brainstore reader and fast reader fleets to finish their instance refreshes before it updates the API ECS services and the API, catchup ETL, automation, and billing Lambda functions, so new API versions don't serve traffic before Brainstore is ready. The apply can take noticeably longer as a result. During the refresh, reader capacity can temporarily double. Writer nodes refresh independently and don't hold up the apply.
>
> > [accordion] If the apply fails while waiting for Brainstore
> >
> > Terraform waits up to 14 minutes for the refreshes, then up to 14 more minutes in the same apply. The apply fails, and API updates stay blocked, if a refresh fails, health checks fail, or the second wait also runs out.
> >
> > Fix the reported failure and rerun `terraform apply`. The apply checks live AWS state and resumes an active refresh. Progress and refresh IDs are logged to the `/braintrust/<deployment_name>/<deployment_name>-BrainstoreDeployment` CloudWatch log group.

> [tab] GCP
>
> 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`.
>
> > [!NOTE]
> >
> > 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\*\*](https://www.braintrust.dev/app/~/configuration/data-plane) in the Braintrust UI.
>
> ## 1. Decide what to upgrade
>
> Before upgrading, check the [Self-hosting releases](https://docs.braintrust.dev/data-plane-changelog.md) 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.
>
> ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> terraform apply
> ```
>
> > [!WARNING]
> >
> > 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](mailto:support@braintrust.dev) for help.
>
> To pin to a specific Terraform module version, update the `?ref=` in your module source:
>
> ```hcl theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> 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](https://github.com/braintrustdata/terraform-google-braintrust-data-plane/releases)
>
> ## 3. Update services (Helm)
>
> Run this step to deploy a new data plane version or apply a Helm chart update.
>
> **1. 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](https://github.com/braintrustdata/helm/blob/main/braintrust/values.yaml) for the exact field names.
>
> **2. Upgrade the Helm chart**
>
> ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> 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).
>
> > [!NOTE]
> >
> > When a release requires both Terraform and Helm changes, apply Terraform first, then run the Helm upgrade.
>
> > [!WARNING]
> >
> > Helm chart 6.20.0 and later enable the [Brainstore startup gate](https://docs.braintrust.dev/admin/self-hosting/configure/scaling.md#brainstore-startup-gate) by default. Before you upgrade, confirm that:
> >
> > * `api.image.tag` is a release tag such as `v2.17.0`, or `api.brainstoreStartupGate.minimumVersion` is set. Otherwise, the chart fails to render.
> > * Every API pool uses the `RollingUpdate` strategy with `maxUnavailable: 0` and a nonzero `maxSurge`. Otherwise, the chart fails to render.
> > * `brainstore.image.tag` is a release tag. If it's a commit SHA, a digest, or a pre-release tag, new API pods don't start. To deploy such an image, set `api.brainstoreStartupGate.enabled: false`.
>
> See all Helm chart releases: [GitHub Releases](https://github.com/braintrustdata/helm/releases)

> [tab] Azure
>
> 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`.
>
> > [!NOTE]
> >
> > 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\*\*](https://www.braintrust.dev/app/~/configuration/data-plane) in the Braintrust UI.
>
> ## 1. Decide what to upgrade
>
> Before upgrading, check the [Self-hosting releases](https://docs.braintrust.dev/data-plane-changelog.md) 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.
>
> ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> terraform apply
> ```
>
> > [!WARNING]
> >
> > 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](mailto:support@braintrust.dev) for help.
>
> To pin to a specific Terraform module version, update the `?ref=` in your module source:
>
> ```hcl theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> 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](https://github.com/braintrustdata/terraform-azure-braintrust-data-plane/releases)
>
> > [!NOTE]
> >
> > 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](https://docs.braintrust.dev/data-plane-changelog.md) 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.
>
> **1. 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](https://github.com/braintrustdata/helm/blob/main/braintrust/values.yaml) for the exact field names.
>
> **2. Upgrade the Helm chart**
>
> ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> 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).
>
> > [!NOTE]
> >
> > When a release requires both Terraform and Helm changes, apply Terraform first, then run the Helm upgrade.
>
> > [!WARNING]
> >
> > Helm chart 6.20.0 and later enable the [Brainstore startup gate](https://docs.braintrust.dev/admin/self-hosting/configure/scaling.md#brainstore-startup-gate) by default. Before you upgrade, confirm that:
> >
> > * `api.image.tag` is a release tag such as `v2.17.0`, or `api.brainstoreStartupGate.minimumVersion` is set. Otherwise, the chart fails to render.
> > * Every API pool uses the `RollingUpdate` strategy with `maxUnavailable: 0` and a nonzero `maxSurge`. Otherwise, the chart fails to render.
> > * `brainstore.image.tag` is a release tag. If it's a commit SHA, a digest, or a pre-release tag, new API pods don't start. To deploy such an image, set `api.brainstoreStartupGate.enabled: false`.
>
> See all Helm chart releases: [GitHub Releases](https://github.com/braintrustdata/helm/releases)

## Next steps

* [Self-hosting releases](https://docs.braintrust.dev/data-plane-changelog.md) — review release notes and infrastructure requirements for each data plane version
* [Configuration](https://docs.braintrust.dev/admin/self-hosting/configure.md) — configure telemetry, network access, rate limiting, and other options


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.