2016-02-01 21:48:37 +00:00
---
2020-01-18 00:18:09 +00:00
layout: docs
page_title: Upgrading Vault - Guides
2016-02-01 21:48:37 +00:00
description: |-
2017-03-08 22:33:58 +00:00
These are general upgrade instructions for Vault for both non-HA and HA
setups. Please ensure that you also read the version-specific upgrade notes.
2016-02-01 21:48:37 +00:00
---
# Upgrading Vault
These are general upgrade instructions for Vault for both non-HA and HA setups.
2017-08-08 20:32:27 +00:00
_Please ensure that you also read any version-specific upgrade notes which can be
2022-04-04 17:04:50 +00:00
found in the sidebar._
2016-02-01 21:48:37 +00:00
2022-08-03 02:05:17 +00:00
!> **Important:** Always back up your data before upgrading! Vault does not
2019-06-10 16:54:21 +00:00
make backward-compatibility guarantees for its data store. Simply replacing the
newly-installed Vault binary with the previous version will not cleanly
downgrade Vault, as upgrades may perform changes to the underlying data
structure that make the data incompatible with a downgrade. If you need to roll
back to a previous version of Vault, you should roll back your data store as
well.
2019-03-09 16:57:51 +00:00
2021-12-20 18:46:57 +00:00
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.
2022-08-09 20:57:58 +00:00
## Integrated Storage Autopilot
2021-07-01 15:12:57 +00:00
2022-08-03 02:05:17 +00:00
Vault 1.11 introduced [automated
2022-08-09 20:57:58 +00:00
upgrades](/docs/concepts/integrated-storage/autopilot#automated-upgrades) as
2022-08-03 02:05:17 +00:00
part of the Integrated Storage Autopilot feature. If your Vault environment is
configured to use Integrated Storage, consider leveraging this new feature to
2022-08-09 20:57:58 +00:00
upgrade your Vault environment.
2022-08-03 02:05:17 +00:00
-> **Tutorial:** Refer to the [Automate Upgrades with Vault
Enterprise](https://learn.hashicorp.com/tutorials/vault/raft-upgrade-automation)
2022-08-09 20:57:58 +00:00
tutorial for more details.
2021-07-01 15:12:57 +00:00
2021-12-20 18:46:57 +00:00
## 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.
2019-03-09 16:57:51 +00:00
## 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.
2017-06-16 17:23:22 +00:00
2020-07-08 13:17:27 +00:00
## OSS to Enterprise Installations
Upgrading to Vault Enterprise installations follow the same steps as OSS upgrades except that the Vault Enterprise binary is to be used and the license file [applied](/api-docs/system/license#install-license), when applicable. The Enterprise binary and license file can be obtained through your HashiCorp sales team.
2016-02-01 21:48:37 +00:00
## 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
2022-08-09 20:57:58 +00:00
!> **Important:** Note that these instructions are not relevant if you're on a
version of Vault greater than or equal to 1.11 and you have Autopilot enabled.
If so, 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](/docs/concepts/integrated-storage/autopilot#automated-upgrades)
documentation for information on this feature and our
[Automate Upgrades with Vault
Enterprise](https://learn.hashicorp.com/tutorials/vault/raft-upgrade-automation)
tutorial for more details.
This is our recommended upgrade procedure if you're on a version of Vault before
1.11, or you've chosen not to use Autopilot. However, you should consider how to
apply these steps to your particular setup since HA setups can differ on whether
a load balancer is in use, what addresses clients are being given to connect to
Vault (standby + leader, leader-only, or discovered via service discovery), etc.
2016-02-01 21:48:37 +00:00
2017-06-16 17:23:22 +00:00
Whatever method you use, you should ensure that you never fail over from a
newer version of Vault to an older version. Our suggested procedure is designed
to prevent this.
2016-08-15 13:42:42 +00:00
Please note that Vault does not support true zero-downtime upgrades, but with
proper upgrade procedure the downtime should be very short (a few hundred
milliseconds to a second depending on how the speed of access to the storage
backend).
2016-02-01 21:48:37 +00:00
Perform these steps on each standby:
1. Properly shut down Vault on the standby node via `SIGINT` or `SIGTERM`
2021-06-18 18:42:55 +00:00
2. Replace the Vault binary with the new version; ensure that `mlock()` capability is added to the new binary with [setcap](/docs/configuration#disable_mlock)
2016-02-01 21:48:37 +00:00
3. Start the standby node
4. Unseal the standby node
2021-06-18 18:42:55 +00:00
5. Verify `vault status` shows correct Version and HA Mode is `standby`
6. Review the node's logs to ensure successful startup and unseal
2016-02-01 21:48:37 +00:00
2016-08-15 13:42:42 +00:00
At this point all standby nodes will be upgraded and ready to take over. The
upgrade will not be complete until one of the upgraded standby nodes takes over
active duty. To do this:
2016-02-01 21:48:37 +00:00
2022-04-04 17:04:50 +00:00
1. Properly shut down the remaining (active) node
2021-06-18 18:42:55 +00:00
2022-04-04 17:04:50 +00:00
~> **Note:** It is important that you shut the node down properly.
2021-06-18 18:42:55 +00:00
This will perform a step-down and release the HA lock, allowing a standby
node to take over with a very short delay.
2016-02-01 21:48:37 +00:00
If you kill Vault without letting it release the lock, a standby node will
not be able to take over until the lock's timeout period has expired. This
is backend-specific but could be ten seconds or more.
2022-04-04 17:04:50 +00:00
2020-01-22 20:05:41 +00:00
2. Replace the Vault binary with the new version; ensure that `mlock()` capability is added to the new binary with [setcap](/docs/configuration#disable_mlock)
2022-04-04 17:04:50 +00:00
3. Start the node
4. Unseal the node
2021-06-18 18:42:55 +00:00
5. Verify `vault status` shows correct Version and HA Mode is `standby`
2022-04-04 17:04:50 +00:00
6. Review the node's logs to ensure successful startup and unseal
2016-02-01 21:48:37 +00:00
2017-06-16 17:23:22 +00:00
Internal upgrade tasks will happen after one of the upgraded standby nodes
takes over active duty.
2016-02-01 21:48:37 +00:00
Be sure to also read and follow any instructions in the version-specific
upgrade notes.
2018-03-26 14:25:09 +00:00
## Replication Installations
-> **Note:** Prior to any upgrade, be sure to also read and follow any instructions in the version-specific
upgrade notes which are found in the navigation menu for this documentation.
2020-01-22 20:05:41 +00:00
Upgrading installations of Vault which participate in [Enterprise Replication](/docs/enterprise/replication) requires the following basic order of operations:
2018-03-26 14:25:09 +00:00
2019-03-09 16:57:51 +00:00
- **Upgrade the replication secondary instances first** using appropriate
guidance from the previous sections depending on whether each secondary
instance is Non-HA or HA
2018-03-26 14:25:09 +00:00
- Verify functionality of each secondary instance after upgrading
2019-03-09 16:57:51 +00:00
- When satisfied with functionality of upgraded secondary instances, upgrade
the primary instance
2021-07-12 17:13:45 +00:00
2021-12-20 18:46:57 +00:00
~> **Note:** It is not safe to replicate from a newer version of Vault to an
older version. When upgrading replicated clusters, ensure that upstream clusters
are always on older versions of Vault than downstream clusters.
Here is an example of upgrading four Vault replicated Vault clusters:
2021-07-12 17:13:45 +00:00
In the above scenario, the ideal upgrade procedure would be as follows,
verifying functionality after each cluster upgrade.
1. Upgrade Clusters B and D, using the HA upgrade process above. 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.
