> ## Documentation Index
> Fetch the complete documentation index at: https://braintrust.dev/docs/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 v2.0? It requires a multi-step migration with irreversible infrastructure changes. Follow the [Upgrade to v2.0](/admin/self-hosting/upgrade/v2) guide instead.
</Note>

<Tabs>
  <Tab title="AWS - Lambda" icon="https://img.logo.dev/aws.amazon.com?token=pk_BdcHD9e5SCW3j1rnJkNyMQ">
    This guide shows the routine process for upgrading the Braintrust data plane in your AWS account.

    ## How it works

    On AWS, the Braintrust data plane runs on Lambda and EC2. 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 **<Icon icon="settings-2" /> Settings** > [**<Icon icon="lock" /> Data plane**](https://www.braintrust.dev/app/~/configuration/org/api-url) in the Braintrust UI.

    ## 1. Update the module version

    Check the [Self-hosting releases](/data-plane-changelog) 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=v4.1.0"

      # ... other configuration ...
    }
    ```

    See all module releases: [GitHub Releases](https://github.com/braintrustdata/terraform-aws-braintrust-data-plane/releases)

    ## 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`.
    </Note>

    Review the planned changes before applying:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    terraform plan
    ```

    <Warning>
      Carefully review the output of `terraform plan` before applying. If you see something unexpected, like deletion of a database or S3 bucket, [contact Braintrust](mailto:support@braintrust.dev) for help.
    </Warning>

    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.
  </Tab>

  <Tab title="GCP" icon="https://img.logo.dev/cloud.google.com?token=pk_BdcHD9e5SCW3j1rnJkNyMQ">
    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.
    </Note>

    To check which data plane version you're currently running, go to **<Icon icon="settings-2" /> Settings** > [**<Icon icon="lock" /> Data plane**](https://www.braintrust.dev/app/~/configuration/org/api-url) in the Braintrust UI.

    ## 1. Decide what to upgrade

    Before upgrading, check the [Self-hosting releases](/data-plane-changelog) 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.
    </Warning>

    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.

    <Steps>
      <Step title="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.
      </Step>

      <Step title="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.
        </Note>

        See all Helm chart releases: [GitHub Releases](https://github.com/braintrustdata/helm/releases)
      </Step>
    </Steps>
  </Tab>

  <Tab title="Azure" icon="https://img.logo.dev/azure.microsoft.com?token=pk_BdcHD9e5SCW3j1rnJkNyMQ">
    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.
    </Note>

    To check which data plane version you're currently running, go to **<Icon icon="settings-2" /> Settings** > [**<Icon icon="lock" /> Data plane**](https://www.braintrust.dev/app/~/configuration/org/api-url) in the Braintrust UI.

    ## 1. Decide what to upgrade

    Before upgrading, check the [Self-hosting releases](/data-plane-changelog) 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.
    </Warning>

    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)

    ## 3. Update services (Helm)

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

    <Steps>
      <Step title="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.
      </Step>

      <Step title="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.
        </Note>

        See all Helm chart releases: [GitHub Releases](https://github.com/braintrustdata/helm/releases)
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Next steps

* [Self-hosting releases](/data-plane-changelog) — review release notes and infrastructure requirements for each data plane version
* [Advanced configuration](/admin/self-hosting/advanced) — configure telemetry, network access, rate limiting, and other options