Upgrade Vault

Vault supports in-place upgrades and automatically handles most tasks when you unseal Vault after the upgrade.

Before you start

• You must have sudo permissions on the Vault server. Make sure you have can install binaries on the Vault server.
• You must have admin permissions for Vault. Make sure you can stop and start the Vault process.
• Identify unseal candidates. Identify and notify enough people with unseal shards to meet the unseal threshold after restart.

Step 1: Isolate your test instance

Upgrade or restore tests should always be performed in a fully isolated network environment. Isolation is critical to prevent both unwanted cluster-to-cluster communication (which maintains data consistency) and to stop the test instance from attempting to revoke 3rd-party credentials (secrets, etc.). If the test instance revokes live credentials, they may expire, which might result in irrevocable leases for the production Vault cluster from which the snapshot was taken.

Here are concrete steps that you can take to effectively isolate the Vault server while testing snapshot restoration and server upgrades.

1. Remove the test server from production load balancers. Deregister the instance from any external or internal load balancer target groups, and confirm no client traffic can still reach the node through service discovery or DNS.

2. Block inbound and outbound network access. Apply restrictive security groups, firewall rules, or ACL rules so the server only allows access from an administrative workstation or bastion host. Deny outbound access to production dependencies unless explicitly required for testing.

3. Place the test server on a separate subnet or VLAN. Move the server into a non-routable test subnet or an isolated network segment, and ensure there is no routing path back to production application networks.

4. Disable cluster participation. Prevent the server from joining or rejoining the production Vault cluster. Verify the server cannot communicate with production storage backends, retry_join targets, or cluster peers.

5. Use separate DNS or no DNS registration. Do not register the instance in production DNS or service discovery. If you require name resolution, use a temporary hostname that clients will not query.

6. Stop or disable automation that could reconnect the test server. Pause auto-scaling, orchestration, configuration management, or monitoring actions that might reattach the host to production. Disable scripts that automatically restart Vault with production settings.

7. Replace production-integrated configuration values. Remove or override production listener addresses, storage settings, seal configuration, telemetry sinks, and audit destinations if they would connect outward. Point the restored instance only to test-safe resources.

8. Restrict operator access paths. Limit administration to a bastion host, VPN, or console session. Log who can access the isolated server during testing.

9. Validate isolation before restore. Test that production clients cannot connect to the instance. Confirm the instance cannot reach production peers, storage, KMS, or service endpoints.

You can confidently restore the snapshot once you:

• Confirm the safety of you network, configuration, and access controls.
• Conduct functional testing with non-production users, tokens, and workflows.

Step 2: Apply the upgrade

To perform an in-place upgrade of a single Vault instance:

1. Back up your Vault data. Vault does not make backward-compatibility guarantees for the Vault data store and the upgrade process may make changes to the data store.

   Backup and restore data

   All Vault editions support snapshot save and restore features for data backup and restoration. Vault Enterprise users benefit from automated snapshots to local or cloud storage, and individual secret recovery.

   Reference the following resources for more details on snapshots.

   • Manage snapshots guide.
   • snapshot CLI command
   • /sys/storage/raft/snapshot-load endpoint

2. Back up your current Vault configuration.

3. Review recent deprecation notices. If you use deprecated or ended functionality, make a plan to move away from those features before upgrading.

4. Use the doc version selector to review the important changes for each major version between your current version and the upgrade target.

5. Perform any prerequisites noted in the important changes documentation.

6. Stop the Vault service.

   BashPowershell

   $ sudo systemctl stop vault
   

   Stop-Process <vault_pid>
   

7. Install the latest version of Vault over your existing instance.

8. Start Vault.

9. Verify the current version:

   $ vault status | grep Version
   

10. Unseal Vault.

Step 3: Test the upgrade

1. Take a snapshot of the Vault data store before starting the upgrade.

2. Restore that snapshot into a non-production test instance.

3. Upgrade Vault in the test environment.

4. Verify that Vault starts successfully after the upgrade.

5. Confirm that data is intact and accessible.

6. Test authentication methods, secrets engines, and any critical workflows.

7. Resolve any issues you find before upgrading your production environment.

Additional resources