Upgrading Vault

These are general upgrade instructions for Vault for both non-HA and HA setups. Please ensure that you also read any version-specific upgrade notes which can be found in the sidebar.

Vault upgrades are designed such that large jumps (ie 1.3.10 -> 1.7.x) are supported. The upgrade notes for each intervening version must be reviewed. The upgrade notes may describe additional steps or configuration to update before, during, or after the upgrade.

We also recommend you consult the deprecation notices. The notice page includes a comprehensive list of deprecated features and the Vault versions where the feature was removed or is scheduled to be removed.

Vault version guidance

HashiCorp regularly releases new versions of Vault in the form of "major" and "minor" releases. Vault typically uses version numbers in the form of X.Y.Z, and very rarely the form X.Y.Z.A.

Vault version numbers do not conform to semver. Vault major releases are identified by a change in the second (Y) digit. Vault minor releases are identified by a change in the third (Z) digit. Vault denotes a release with Enterprise only changes using the fourth (A) digit. HashiCorp's Support and End-of-Life policy covers versioning in more detail.

HashiCorp does not require upgrading to each major (Y digit) Vault release immediately when it becomes available. HashiCorp does strongly encourage upgrading Vault to the latest minor (Z digit) patch in a supported major release.

To be notified of new Vault releases, users can subscribe to our Discuss Forum using the vault-release-ce-ent tag. New security bulletins are also available on Discuss via the security-vault tag.

Integrated storage autopilot

Vault 1.11 introduced automated upgrades as part of the Integrated Storage Autopilot feature. If your Vault environment is configured to use Integrated Storage, consider leveraging this new feature to upgrade your Vault environment.

Agent

The Vault Agent is an API client of the Vault Server. Vault APIs are almost always backwards compatible. When they are not, this is called out in the upgrade guide for the new Vault version, and there is a lengthy deprecation period. The Vault Agent version can lag behind the Vault Server version, though we recommend keeping all Vault instances up to date with the most recent minor Vault version to the extent possible.

Testing the upgrade

It's always a good idea to try to ensure that the upgrade will be successful in your environment. The ideal way to do this is to take a snapshot of your data and load it into a test cluster. However, if you are issuing secrets to third party resources (cloud credentials, database credentials, etc.) ensure that you do not allow external network connectivity during testing, in case credentials expire. This prevents the test cluster from trying to revoke these resources along with the non-test cluster.

Upgrading from Community to Enterprise editions

Upgrading to Vault Enterprise installations follow the same steps as Community edition upgrades except that the Vault Enterprise binary is to be used and the license file applied, when applicable. The Enterprise binary and license file can be obtained through your HashiCorp sales team.

Non-HA installations

Upgrading non-HA installations of Vault is as simple as replacing the Vault binary with the new version and restarting Vault. Any upgrade tasks that can be performed for you will be taken care of when Vault is unsealed.

Always use SIGINT or SIGTERM to properly shut down Vault.

Be sure to also read and follow any instructions in the version-specific upgrade notes.

HA installations

The recommended upgrade procedure depends on the version of Vault you're currently on and the storage backend of Vault. If you're currently running on Vault 1.11 or later with Integrated Storage and you have Autopilot enabled, you should let Autopilot do the upgrade for you, as that's easier and less prone to human error. Please refer to our automated upgrades documentation for information on this feature and our Automate Upgrades with Vault Enterprise tutorial for more details.

If you're currently on a version of Vault before 1.11, or you've chosen to opt-out the Autopilot automated upgrade features when running Vault after 1.11 with Integrated Storage, or if you are running Vault with other storage backend such as Consul. Please refer to our Vault HA upgrades Pre 1.11/Without Autopilot Upgrade Automation documentation for more details. Please note that this upgrade procedure also applies if you are upgrading Vault from pre 1.11 to post 1.11.

Enterprise replication installations

Upgrading Vault Enterprise clusters which participate in Enterprise Replication requires the following basic order of operations:

• Upgrade the replication secondary instances first using appropriate guidance from the previous sections
• Verify functionality of each secondary instance after upgrading
• When satisfied with functionality of upgraded secondary instances, upgrade the primary instance

Here is an example of upgrading four Vault replicated Vault clusters:

In the above scenario, the ideal upgrade procedure would be as follows, verifying functionality after each cluster upgrade.

1. Upgrade Clusters B and D. These clusters have no downstream clusters, so they should be upgraded first, but the ordering of B vs D does not matter.
2. Upgrade Cluster C, which now has an upgraded downstream cluster (Cluster D). Because Cluster C is a cluster, it should also use the HA upgrade process.
3. Finally, upgrade Cluster A. All clusters downstream of A will already be upgraded. It should be upgraded last, as it is a Performance Primary and a DR Primary.