• Overview
    • Automated PKI Infrastructure
    • Data Encryption & Tokenization
    • Database Credential Rotation
    • Dynamic Secrets
    • Identity-based Access
    • Key Management
    • Kubernetes Secrets
    • Secrets Management
  • Enterprise
  • Tutorials
  • Docs
  • API
  • Community
GitHubTry Cloud
Download
    • v1.11.x (latest)
    • v1.10.x
    • v1.9.x
    • v1.8.x
    • v1.7.x
    • v1.6.x
    • v1.5.x
    • v1.4.x
  • What is Vault?
  • Use Cases
    • CLI Quick Start
    • HCP Quick Start
    • Developer Quick Start

  • Browser Support
  • Installing Vault
    • Overview
    • Architecture
    • High Availability
    • Integrated Storage
    • Security Model
    • Telemetry
    • Token Authentication
    • Key Rotation
    • Replication
    • Limits and Maximums
    • Overview
    • 'Dev' Server
    • Seal/Unseal
    • Namespace API Lock
    • Lease, Renew, and Revoke
    • Authentication
    • Tokens
    • Identity
    • OIDC Provider
    • Response Wrapping
    • Policies
    • Password Policies
    • Username Templating
    • High Availability
    • Storage
      • Overview
      • Autopilot
    • PGP, GnuPG, and Keybase
    • Recovery Mode
    • Resource Quotas
      • Overview
      • FAQ
    • Transform
    • Mount Migration
    • Overview
      • Overview
      • TCP
    • replication
      • Overview
      • AliCloud KMS
      • AWS KMS
      • Azure Key Vault
      • GCP Cloud KMS
      • OCI KMS
      • HSM PKCS11 ENT
      • Vault Transit
    • sentinel
      • Overview
      • Consul
      • Kubernetes
      • Overview
      • Aerospike
      • Alicloud OSS
      • Azure
      • Cassandra
      • CockroachDB
      • Consul
      • CouchDB
      • DynamoDB
      • Etcd
      • Filesystem
      • FoundationDB
      • Google Cloud Spanner
      • Google Cloud Storage
      • In-Memory
      • Manta
      • MSSQL
      • MySQL
      • OCI Object Storage
      • PostgreSQL
      • Integrated Storage (Raft)
      • S3
      • Swift
      • Zookeeper
    • telemetry
    • ui
    • Log Completed Requests
    • Entropy Augmentation ENT
    • kms_library ENT
    • Overview
    • agent
      • Overview
      • disable
      • enable
      • list
      • Overview
      • disable
      • enable
      • help
      • list
      • move
      • tune
    • debug
    • delete
      • Overview
      • delete
      • destroy
      • enable-versioning
      • get
      • list
      • metadata
      • patch
      • put
      • rollback
      • undelete
      • Overview
      • lookup
      • renew
      • revoke
      • Overview
      • get
      • inspect
    • list
    • login
    • monitor
    • namespace
      • Overview
      • diagnose
      • generate-root
      • init
      • key-status
      • members
      • migrate
      • raft
      • rekey
      • rotate
      • seal
      • step-down
      • unseal
      • usage
    • path-help
      • Overview
      • deregister
      • info
      • list
      • register
      • reload
      • Overview
      • delete
      • fmt
      • list
      • read
      • write
    • read
      • Overview
      • disable
      • enable
      • list
      • move
      • tune
    • server
    • ssh
    • status
      • Overview
      • capabilities
      • create
      • lookup
      • renew
      • revoke
    • unwrap
    • version
    • version-history
    • write
    • Token Helpers
    • Overview
      • Overview
        • Overview
        • AliCloud
        • AppRole
        • AWS
        • Azure
        • Cert
        • CF
        • GCP
        • JWT
        • Kerberos
        • Kubernetes
        • Overview
        • File
      • Overview
        • Overview
        • Kubernetes
    • Templates
    • Windows service

    • Overview
    • Active Directory
    • AliCloud
    • AWS
    • Azure
    • Consul
    • Cubbyhole
      • Overview
      • Cassandra
      • Couchbase
      • Elasticsearch
      • HanaDB
      • IBM Db2
      • InfluxDB
      • MongoDB
      • MongoDB Atlas
      • MSSQL
      • MySQL/MariaDB
      • Oracle
      • PostgreSQL
      • Redshift
      • Snowflake
      • Custom
    • Google Cloud
    • Google Cloud KMS
      • Overview
      • Identity Tokens
      • OIDC Identity Provider
      • Overview
      • Azure Key Vault
      • AWS KMS
      • GCP Cloud KMS
      • Overview
      • K/V Version 1
      • K/V Version 2
    • KMIP ENTERPRISE
    • Kubernetes
    • MongoDB Atlas
    • Nomad
    • OpenLDAP
      • Overview
      • Setup and Usage
      • Quick Start - Root CA Setup
      • Quick Start - Intermediate CA Setup
      • Considerations
      • Rotation Primitives
    • RabbitMQ
      • Overview
      • Signed Certificates
      • SSH OTP
      • Dynamic Key
    • Terraform Cloud
    • TOTP
      • Overview
      • FF3-1 Tweak Usage
      • Tokenization Transform ENTERPRISE
    • Transit
    • Venafi (Certificates)
    • Overview
    • AppRole
    • AliCloud
    • AWS
    • Azure
    • Cloud Foundry
    • GitHub
    • Google Cloud
      • Overview
      • OIDC Providers
    • Kerberos
    • Kubernetes
    • LDAP
      • Overview
      • FAQ
    • Oracle Cloud Infrastructure
    • Okta
    • RADIUS
    • TLS Certificates
    • Tokens
    • Username & Password

    • App ID DEPRECATED
    • Overview
    • File
    • Syslog
    • Socket
    • Overview
    • Plugin Architecture
    • Plugin Development
    • Plugin Management
    • Plugin Portal
  • Vault Integration Program
  • Troubleshoot

    • Overview
      • Overview
      • Agent Injector vs. Vault CSI Provider
        • Overview
        • Running Vault
        • Enterprise Licensing
        • Running Vault on OpenShift
        • Configuration
          • Overview
          • Development
          • Standalone with Load Balanced UI
          • Standalone with TLS
          • Standalone with Audit Storage
          • External Vault
          • Using Kubernetes Auth Method
          • HA Cluster with Consul
          • HA Cluster with Raft
          • HA Enterprise Cluster with Raft
          • HA Enterprise DR Clusters with Raft
          • HA Enterprise Performance Clusters with Raft
          • Vault Agent Injector TLS Configuration
          • Vault Agent Injector TLS with Cert-Manager
        • Overview
        • Annotations
        • Installation
        • Examples
        • Overview
        • Installation
        • Configurations
        • Examples
      • Overview
      • Vault Lambda Extension
      • Running Vault
      • Overview
      • Installation
      • Configuration
      • Troubleshooting
      • Overview
      • Installation
      • Configuration
      • Upgrading
      • Troubleshooting

    • Overview
    • Upgrade Plugins
    • Upgrade to 1.11.x
    • Upgrade to 1.10.x
    • Upgrade to 1.9.x
    • Upgrade to 1.8.x
    • Upgrade to 1.7.x
    • Upgrade to 1.6.3
    • Upgrade to 1.6.2
    • Upgrade to 1.6.1
    • Upgrade to 1.6.0
    • Upgrade to 1.5.3
    • Upgrade to 1.5.2
    • Upgrade to 1.5.1
    • Upgrade to 1.5.0
    • Upgrade to 1.4.6
    • Upgrade to 1.4.5
    • Upgrade to 1.4.4
    • Upgrade to 1.4.1
    • Upgrade to 1.4.0
    • Upgrade to 1.3.10
    • Upgrade to 1.3.9
    • Upgrade to 1.3.8
    • Upgrade to 1.3.5
    • Upgrade to 1.3.4
    • Upgrade to 1.3.3
    • Upgrade to 1.3.2
    • Upgrade to 1.3.0
    • Upgrade to 1.2.7
    • Upgrade to 1.2.6
    • Upgrade to 1.2.5
    • Upgrade to 1.2.4
    • Upgrade to 1.2.1
    • Upgrade to 1.2.0
    • Upgrade to 1.1.2
    • Upgrade to 1.1.1
    • Upgrade to 1.1.0
    • Upgrade to 1.0.0
    • Upgrade to 0.11.6
    • Upgrade to 0.11.2
    • Upgrade to 0.11.0
    • Upgrade to 0.10.4
    • Upgrade to 0.10.2
    • Upgrade to 0.10.0
    • Upgrade to 0.9.6
    • Upgrade to 0.9.3
    • Upgrade to 0.9.2
    • Upgrade to 0.9.1
    • Upgrade to 0.9.0
    • Upgrade to 0.8.0
    • Upgrade to 0.7.0
    • Upgrade to 0.6.4
    • Upgrade to 0.6.3
    • Upgrade to 0.6.2
    • Upgrade to 0.6.1
    • Upgrade to 0.6.0
    • Upgrade to 0.5.1
    • Upgrade to 0.5.0

    • Overview
    • 1.11.0
    • 1.10.0
    • 1.9.0
    • 1.8.0
    • 1.7.0
    • 1.6.0
    • 1.5.0

    • Overview
    • FAQ

    • Overview
    • Feature Deprecation Notice and Plans
    • License
    • Client Count
    • Login MFA
    • Server Side Consistent Token

  • Glossary

    • Overview
      • Overview
      • Autoloading
      • FAQ
    • Replication
      • Overview
      • Behavioral Changes
      • Security
    • Automated Integrated Storage Snapshots
    • Automated Upgrades
    • Redundancy Zones
    • Lease Count Quotas
    • Entropy Augmentation
      • Overview
      • FIPS 140-2 Inside Vault
      • Seal Wrap for FIPS 140-2
    • Seal Wrap
    • Namespaces
    • Performance Standbys
    • Eventual Consistency
    • Control Groups
    • Managed Keys
      • Overview
      • Duo MFA
      • Okta MFA
      • PingID MFA
      • TOTP MFA
      • Overview
      • Examples
      • Properties
    • HCP Vault

The Vault website is being redesigned to help you find what you are looking for more effectively.

Type '/' to Search

»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.

IMPORTANT NOTE: Always back up your data before upgrading! Vault does not 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.

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.

»Tutorial

Refer to the Vault Upgrade Standard Procedure tutorial to learn how to upgrade Vault Enterprise.

»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.

»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, 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

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.

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.

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).

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; ensure that mlock() capability is added to the new binary with setcap
  3. Start the standby node
  4. Unseal the standby node
  5. Verify vault status shows correct Version and HA Mode is standby
  6. Review the node's logs to ensure successful startup and unseal

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:

  1. Properly shut down the remaining (active) node

    Note: It is important that you shut the node down properly. This will perform a step-down and release the HA lock, 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.

  2. Replace the Vault binary with the new version; ensure that mlock() capability is added to the new binary with setcap

  3. Start the node

  4. Unseal the node

  5. Verify vault status shows correct Version and HA Mode is standby

  6. Review the node's logs to ensure successful startup and unseal

Internal upgrade tasks will happen after one of the upgraded standby nodes takes over active duty.

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

»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.

Upgrading installations of Vault 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 depending on whether each secondary instance is Non-HA or HA
  • Verify functionality of each secondary instance after upgrading
  • When satisfied with functionality of upgraded secondary instances, upgrade the primary instance

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:

Upgrading multiple replicated 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, 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.
github logoEdit this page
DocsAPILearnCommunityPrivacySecurityPress KitConsent Manager