Skip to main content

Vault migration options

Manage upgrades and downgrades of your Vault​

note

If you're using the hosted version of Vault, Piiano manages the upgrade of Vault software.

Overview​

New Vault versions might need to migrate their internal database schema. This can be due to the introduction of new features, improvements, security patches, bug fixes, performance optimizations, and more.

To facilitate this process, The Vault has two solutions to perform the necessary migrations.

  1. Automatic built-in migration
  2. pvault-migrate CLI
danger

While the migration system is designed to be safe and non-destructive, it is always a good idea to take the following safety measures. This is especially important when upgrading from very old versions of Vault, as the database schema may have changed significantly and the migration may not be able to properly handle all of the necessary changes.

  • Check the release notes for any breaking changes or special considerations for the version you are upgrading to.
  • Take a backup of your data before the migration. This is important in case anything goes wrong during the migration process and you need to revert to a previous state.
  • Test the migration on a staging environment before running it on production.
  • If you encounter any issues during the migration, check the logs for any error messages, fix the issues mentioned in the logs and rerun the migration. Alternatively, you can consider rolling back to the previous version.

Automatic built-in migration​

Vault comes with a built-in migration system that automatically detects when a schema migration is needed and runs it. This is done when Vault starts up and checks the schema version stored in the database. If it is out of date compared to the starting Vault version, it will run the necessary migrations to bring it up to the latest version.

However, in some cases, it may be desirable to disable this automatic migration. To do so, set the PVAULT_DB_MIGRATION_AUTO_RUN environment variable to false.

Vault's built-in migration system is designed to work even when running concurrently. If you have a cluster of Vaults and you upgrade multiple instances simultaneously, the individual built-in migration of each instance will run. The process is expected to pass successfully thanks to a retry mechanism that is backed into the migration process. When multiple instances start, one of them will acquire exclusive access to upgrade the Vault, and the others will start when the upgrade is completed successfully. The process is designed to be robust against failures. Fine-tuning this process can be achieved using the relevant configuration options.

pvault-migrate CLI​

The pvault-migrate CLI provides more fine-grained control over the migration process. It allows you to upgrade or downgrade the schema to a specific version of Vault. The pvault-migrate tool also supports listing available versions and printing the current Vault version. Similar to the pvault CLI, the pvault-migrate binary is also bundled with every Vault image and can be accessed using docker exec/docker run commands.

Configuration options​

To use the pvault-migrate tool, you will need to provide connection details for your database. This can be done is several ways:

Using the --connection-string flag​

When used as a stand-alon tool, you can use the --connection-string flag to specify a connection string in the following format:

user=%s password=%s dbname=%s host=%s port=%d sslmode=%s
Example
pvault-migrate version --connection-string 'user=pvault password=pvault dbname=pvault host=localhost port=5432 sslmode=false'

Using environment variables​

You can rely on existing configuration available in the environment where the tool is used. Considering the pvault-migrate is delivered within the Vault images it is reasonable that it will be executed in environment where the DB credential are available either as the Vault environment variables or configuration files.

Commands​

It offers the following commands:

  • up: upgrades Vault to the latest version.
  • upto: upgrades Vault to a specific version.
  • down: downgrades Vault one version down.
  • downto: downgrades Vault to a specific version.
  • list: lists all available versions that can be migrated to.
  • version: prints the current version of Vault.

Here are some examples of how to use the pvault-migrate tool

The up command​

Upgrade Vault to the latest version. This command is useful for keeping your Vault installation up-to-date with the latest features and improvements.

Command
pvault-migrate up
Output
+-------------+-------------+
| old_version | new_version |
+-------------+-------------+
| 0.9.7       | 1.0.1       |
+-------------+-------------+

The upto command​

Upgrade Vault to a specific version. This command is useful if you know which version you need, for example if you want to upgrade to a version prior to one that introduced a breaking change.

Command
pvault-migrate upto --version 1.0.0
Output
+-------------+-------------+
| old_version | new_version |
+-------------+-------------+
| 0.9.7       | 1.0.0       |
+-------------+-------------+

The down command​

Downgrade Vault by one version. This command is useful for users who have encountered an issue after upgrading and want to identify the latest version of Vault that works for them without the issue.

Command
pvault-migrate down
Output
+-------------+-------------+
| old_version | new_version |
+-------------+-------------+
| 1.0.1       | 1.0.0       |
+-------------+-------------+

The downto command​

Downgrade Vault to a specific version. This is useful if you know exactly which version you need and don't want. For example, if you know that a certain version introduced a breaking change and you want to revert to a version prior to that change.

Command
pvault-migrate downto --version 0.9.7
Output
+-------------+-------------+
| old_version | new_version |
+-------------+-------------+
| 1.0.1       | 0.9.7       |
+-------------+-------------+

The list command​

List all available versions that can be migrated to. This command can be helpful if you want to see the different versions that are available and choose which one to upgrade or downgrade to.

Command
pvault-migrate list
Output
+----------+
| version  |
+----------+
| empty-db |
| 0.9.7    |
| 0.9.8    |
| 1.0.0    |
| 1.0.1    |
+----------+

The version command​

Prints the current version of Vault and the version of pvault-migrate. This can be useful if you want to quickly check the version of Vault you are running and verify that you are using the expected version of pvault-migrate.

Command
pvault-migrate version
Output
+------------------------+---------------+
| pvault_migrate_version | vault_version |
+------------------------+---------------+
| 1.0.1.324606-g534ae0c  | 1.0.0         |
+------------------------+---------------+

Analytics and crash reports​

Similar to the Vault, the migration CLI also collect metrics, usage data and error reports.

These can be disabled using the standard Vault variables PVAULT_SENTRY_ENABLE=false and PVAULT_LOG_DATADOG_ENABLE=false or using the TOML configuration file.

See Logs for more information on logs and telemetry.

On this page