Upgrade path analyzer
Enterprise
Appropriate Vault Enterprise license required
The upgrade path analyzer helps operators plan and execute Vault upgrades directly from the Vault GUI. When you select a target version, the analyzer reviews potential breaking changes, new behavior, and known issues between your current version and the target release. It also generates an ordered upgrade checklist and rollback guidance tailored to your cluster's replication topology.
Before you start
- You must have permission to read release information and version metadata.
Step 1: Open the Upgrade path analyzer
- Sign in to the Vault GUI.
- In the sidebar, select Support.
- Select Upgrade path analyzer.
Step 2: Select a target version and analyze
The upgrade path analyzer displays your current version and populates the Target version dropdown with the latest release for each newer minor version line.
- Choose a target release from the Target version dropdown menu.
- Click Analyze to generate the upgrade analysis.
If your cluster already runs the most recent available release, the analyzer displays a message stating that your cluster is up-to-date and requires no upgrade path analysis.
Step 3: Review upgrade findings and details
After analysis completes, the analyzer presents four summary cards:
- Known issues: Lists documented issues found in releases between your current version and the selected target version that are not fixed by the target version.
- Breaking changes: Summarizes functional breaking changes introduced between your current version and the target version.
- New behavior: Summarizes new features and behavioral updates introduced in the selected version range.
- Rollback steps: Summarizes the procedure to safely roll back the upgrade if needed.
Click View on any summary card to inspect detailed information. Each item displays its affected edition, whether workarounds or recommendations are available, and links to relevant documentation.
Step 4: Follow ordered upgrade steps
The analyzer generates an ordered sequence and detailed upgrade checklist based on your cluster configuration:
- Single instance: Outlines steps to create a pre-upgrade Raft snapshot backup, stop Vault, preserve cluster configuration, install the target version, start Vault, and unseal if needed.
- Replicated deployments: Outlines a topology-aware sequence that upgrades disaster recovery (DR) and performance replication secondaries before upgrading primary clusters, including per-secondary snapshot backups.
Click Download steps to export the ordered checklist and guidance text as a local text file.
CLI and API quick reference
Click CLI & API quick reference in the page header to open a reference modal with common administrative commands:
- Check current version:
$ vault status | grep Version - Create primary snapshot:
$ vault operator raft snapshot save primary.snap - Verify post-upgrade cluster:
$ vault status