Upgrade Boundary and migrate the database

Upgrade a self-managed Boundary deployment by determining whether the release requires a database migration, backing up and migrating the PostgreSQL database when required, and upgrading the controllers and workers. Boundary only supports offline database migrations, so upgrades that change the database schema require downtime.

Requirements

Before you upgrade Boundary, complete the following tasks:

• Review the release notes for the target version and every version between your current and target versions. Follow any version-specific upgrade instructions.
• If you run Boundary 0.20.5, 0.21.5, 0.21.6, 1.0.2, 1.0.3, or 1.1.0, review the recommended upgrade paths before you choose a target version.
• Download and verify the Boundary binary for the target version. Refer to Install Boundary for instructions.
• Confirm that your PostgreSQL version meets the database requirements.
• If the target release requires a database migration, schedule downtime and verify that you can restore the Boundary database from a backup. You must stop every controller before you back up and migrate the database. You cannot revert to an earlier Boundary version after you migrate the database.

Recommended upgrade paths

Some Boundary releases include database migrations that were added to older release lines. When you upgrade from an affected version, Boundary can skip required migrations. As a result, the upgrade can fail or appear to succeed while leaving the database in an incorrect state.

The issue affects upgrades from the versions in the first column of the following table:

Existing installations

Boundary 0.20.5, 0.21.5, and 0.21.6 installations have the database schema required for those versions. The issue occurs only when you upgrade from one of these versions.

An upgrade from 1.0.2 or 1.0.3 to 1.1.0 can report a successful migration even when required tables are missing. If you upgraded from an earlier Boundary release to 1.1.0, upgrade to 1.1.1, even if the migration completed without errors.

New installations of 1.1.0 are not affected. We recommend that you upgrade all existing 1.1.0 clusters to 1.1.1.

Determine whether to migrate the database

Review the release notes for your target version and every version between your current and target versions. If the releases include database schema changes, follow the backup and migration procedure in this topic.

If the release notes confirm that the upgrade does not require a database migration, skip the backup and migration procedure. For example, Boundary 1.0.1 did not include database schema changes, so an upgrade from Boundary 1.0.0 to 1.0.1 does not require a database migration. Do not assume that other patch releases omit schema changes. Check the release notes for each upgrade.

For a Kubernetes deployment that uses the Boundary controller Helm chart, you can perform a rolling upgrade when no database migration is required. Follow the controller Helm chart upgrade procedure. The chart's rolling update settings keep controller pods available while Kubernetes replaces them.

Back up the database

PostgreSQL supports backups while applications continue to read from and write to the database. For this upgrade workflow, stop every Boundary controller before you create the final pre-upgrade backup. Stopping the controllers prevents Boundary from committing transactions after the backup begins and creates a clean recovery point immediately before the migration.

1. Stop every Boundary controller process so that no controller can write to the database. For example, stop the Boundary system service on each controller host, stop each controller container, or scale a Kubernetes controller deployment to zero replicas.
2. Back up the Boundary PostgreSQL database using your organization's backup process. For production environments, use an automated physical backup process configured for point-in-time recovery. Point-in-time recovery uses a base backup and archived PostgreSQL write-ahead log records to restore the database to a selected time, such as immediately before the migration. Refer to the PostgreSQL continuous archiving and point-in-time recovery documentation for requirements and instructions.
3. Verify that you can restore the backup.

Keep the backup until you verify that the upgraded deployment operates correctly. Do not restart the controllers until you migrate the database.

Upgrade the controllers and migrate the database

1. Replace the Boundary binary on every controller with the target version, but do not start the controllers.

2. From one controller, migrate the database using the target-version binary and the controller configuration file:

   $ boundary database migrate -config=/etc/boundary.d/boundary-controller.hcl
   

   The command reports Migrations successfully run. when the migration completes. Refer to the boundary database migrate command reference for additional options, including how to specify a separate migration database URL.

   If the migration fails and the output or release notes instruct you to run a repair, rerun the migration with the provided repair migration version:

   $ boundary database migrate -config=/etc/boundary.d/boundary-controller.hcl -repair=REPAIR_MIGRATION_VERSION
   

   Do not use -repair unless Boundary provides the repair migration version. The flag repairs data required by a specific migration. It does not reverse a migration or downgrade the database schema. For Kubernetes deployments, follow the controller Helm chart repair migration procedure.

3. After the migration succeeds, start the Boundary service on each controller.

4. Verify that all controllers are running the target version and can connect to the database.

5. Verify that you can authenticate to Boundary and perform expected operations before you continue.

Upgrade the workers

Upgrade all workers to the same Boundary version as the controllers to maintain protocol compatibility.

For each worker:

1. Stop the Boundary worker process.
2. Replace the Boundary binary with the target version.
3. Start the Boundary service.
4. Verify that the worker reconnects to its upstream controller or worker and reports the target version.

More information

• Boundary high availability installation
• Boundary system requirements
• boundary database migrate command reference