2016-02-01 21:48:37 +00:00
---
2017-06-29 13:43:43 +00:00
layout: "guides"
2017-03-08 22:33:58 +00:00
page_title: "Upgrading Vault - Guides"
2017-06-29 13:43:43 +00:00
sidebar_current: "guides-upgrading"
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
found in the sidebar._
2016-02-01 21:48:37 +00:00
2017-06-16 17:23:22 +00:00
**Always** back up your data before upgrading! Vault does not make
backwards-compatibility guarantees for its data store. If you need to roll back
to a previous version of Vault, it is always a good idea to roll back your data
store as well.
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
2016-08-15 13:42:42 +00:00
This is our recommended upgrade procedure, and the procedure we use internally
at HashiCorp. 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`
2. Replace the Vault binary with the new version
3. Start the standby node
4. Unseal the standby node
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
1. Properly shut down the remaining (active) node. Note: it is _**very
important**_ that you shut the node down properly. This causes the HA lock to
be released, allowing a standby node to take over with a very short delay.
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.
2017-12-04 15:56:16 +00:00
2. Replace the Vault binary with the new version; ensure that `mlock()` capability is added to the new binary with [setcap ](https://www.vaultproject.io/docs/configuration/index.html#disable_mlock )
2016-02-01 21:48:37 +00:00
3. Start the node
4. Unseal the node (it will now be a standby)
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.
