Upgrade/Downgrade

Upgrade

We currently support (and test) zero downtime sequential upgrades from one minor version to the next minor version. For example, if you’re on version 1.0.0 then you can safely upgrade to 1.0.X or 1.1.X without any downtime.

To upgrade, deploy the new version of the helm chart. The exact steps vary depending on how you use helm — directly, with helmfile, or through CI. If using helm directly, upgrade the Helm chart on the cluster using the the bsr.yaml Helm values file you created during installation:

$ helm upgrade bsr oci://us-docker.pkg.dev/buf-images-1/bsr/charts/bsr \
  --version "1.x.x" \
  --namespace=bsr \
  --values bsr.yaml

Multi-version upgrades

If you want to upgrade more than one minor version (e.g. 1.0.0 to 1.2.0) and you care about avoiding downtime then you need to apply minor version upgrades one at a time (e.g. deploy 1.1.0, verify deploy successful, deploy 1.2.0, verify deploy successful, etc.).

If you are ok with downtime and prefer to minimize the number of steps required to upgrade across multiple versions, you can use the following process (note that this only saves you time if you are upgrading 3 or more minor versions at once):

1. Using the currently deployed version of the helm chart, enable maintenance mode in the helm values, and apply it (e.g. deploy 1.0.0 with maintenance: true).
2. Verify that the deploy has completed.
3. Take a snapshot of the Postgres database, to guard against data loss in case a rollback is necessary.
4. Apply the latest version of the helm chart with maintenance mode disabled in the helm values (e.g. deploy 1.9.0 with maintenance: false or omitted).

Downgrade

It is safe to downgrade to any previous patch version of the same major and minor version with no downtime or dataloss (e.g. downgrade from 1.1.9 to 1.1.0). All you need to do is deploy the previous patch version that you want to roll back to.

It is also safe to downgrade one minor version with no downtime. For example, if an instance is on version 1.2.3 then you can downgrade back to 1.1.0 using the following process:

1. Deploy the version you want to roll back to (e.g. 1.1.0). This is safe to do as a rolling deployment, so that you don't incur downtime.
2. Ensure that the rollback has completed and there are no more instances of the newer version (e.g. 1.2.0) running.
3. Look up the schema version for the version you have rolled back to in the BSR Release Notes (e.g. the database schema version for 1.1.0 is 222).
4. Manually run bufd migratedownto $VERSION using the bufd binary you are rolling back from and the schema version you looked up in the release notes (e.g. with 1.2.0 binary run bufd migratedownto 222 to downgrade to the 1.1.0 schema).