mirror of
https://github.com/hashicorp/vault.git
synced 2025-08-22 15:11:07 +02:00
0660ea6fac
* Update README Let contributors know that docs will now be located in UDR * Add comments to each mdx doc Comment has been added to all mdx docs that are not partials * chore: added changelog changelog check failure * wip: removed changelog * Fix content errors * Doc spacing * Update website/content/docs/deploy/kubernetes/vso/helm.mdx Co-authored-by: Tu Nguyen <im2nguyen@users.noreply.github.com> --------- Co-authored-by: jonathanfrappier <92055993+jonathanfrappier@users.noreply.github.com> Co-authored-by: Tu Nguyen <im2nguyen@users.noreply.github.com>
70 lines
5.2 KiB
Plaintext
70 lines
5.2 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: Automatically upgrade Vault clusters
|
|
description: >-
|
|
Use automated upgrades to simplify cluster upgrades.
|
|
---
|
|
|
|
> [!IMPORTANT]
|
|
> **Documentation Update:** Product documentation, which were located in this repository under `/website`, are now located in [`hashicorp/web-unified-docs`](https://github.com/hashicorp/web-unified-docs), colocated with all other product documentation. Contributions to this content should be done in the `web-unified-docs` repo, and not this one. Changes made to `/website` content in this repo will not be reflected on the developer.hashicorp.com website.
|
|
|
|
# Automatically upgrade Vault clusters
|
|
|
|
@include 'alerts/enterprise-only.mdx'
|
|
|
|
Operators running Vault Enterprise with integrated storage can use automated
|
|
upgrades to upgrade the Vault version currently running in a cluster automatically.
|
|
There are a few different ways to make this upgrade happen,
|
|
and control which versions are being upgraded to. With no additional configuration,
|
|
Vault will check the version of Vault that each node in the cluster is running. If a blue/green
|
|
style deployment is desired, Vault uses the version of your choosing, regardless of
|
|
which version of Vault is currently running.
|
|
|
|
## Configuration
|
|
A new key can be added to Vault's `storage` configuration stanza: `autopilot_upgrade_version`.
|
|
The value for this key is a [SemVer](https://semver.org/) compatible version string of your choosing.
|
|
When a version string is present, it will override the current version of Vault that is running to upgrade automatically.
|
|
|
|
## Mechanics
|
|
Whether you choose to use Vault's built-in version or a version of your own, the mechanics for performing
|
|
automatic upgrades remain the same.
|
|
|
|
When a Vault cluster is running and new nodes containing an updated Vault version join the cluster, the
|
|
Autopilot subsystem within Vault will promote the new version nodes to voters when the number of nodes
|
|
running the latest Vault version equals or exceeds the number of pre-existing nodes. Vault then demotes
|
|
the previous version's nodes to non-voters. Finally, leadership transfers from the prior leader to a
|
|
randomly selected node running the newest Vault version and waits for the user to remove the previous
|
|
nodes from the cluster. Be aware that Autopilot [dead server cleanup](/vault/docs/concepts/integrated-storage/autopilot#dead-server-cleanup) automatically removes nodes deemed unhealthy from the Raft cluster when enabled.
|
|
|
|
Below is a flowchart depicting Autopilot's automated upgrade state machine.
|
|
|
|
|
|
|
|
The status of the automated upgrade can be monitored by consulting the [Autopilot state API endpoint](/vault/api-docs/system/storage/raftautopilot#get-cluster-state).
|
|
|
|
## Examples
|
|
### Using vault's built-in version
|
|
This is the easiest method to perform an automated upgrade; no configuration is needed, and automated upgrades
|
|
are enabled by default.
|
|
|
|
### Using a blue/green style deploy
|
|
Specify something like: `1.11.0-release.1` for the `autopilot_upgrade_version` configuration key in your
|
|
existing cluster. When you're ready to deploy a new set of nodes, specify `1.11.0-release.2` for the new
|
|
nodes. Any time you need to deploy an updated set of nodes to the cluster, increment the final number.
|
|
|
|
It's important to note that Autopilot uses strict [semantic versioning](https://semver.org) when parsing
|
|
upgrade versions. This means that in the above example, `-release.1` is considered the _pre-release version_
|
|
in semantic versioning terminology. The pre-release version is denoted by a hyphen `-` after the patch version.
|
|
This is semantically different from the _build metadata_, which is denoted by a plus sign `+` after either the
|
|
patch version or the pre-release version. Build metadata is ignored when parsing versions, while the pre-release
|
|
version is not. A table with some examples will help illustrate this.
|
|
|
|
| Current upgrade version | New node upgrade version | Equal? | Will the upgrade happen? | Why? |
|
|
|:------------------------|:-------------------------|:-------|:-------------------------|:-----------------------------------------------------------------------------------|
|
|
| 1.11.0 | 1.11.0 | Yes | No | Versions are equal |
|
|
| 1.11.0-release.1 | 1.11.0-release.2 | No | Yes | New node version is greater than current version |
|
|
| 1.11.0-release.1 | 1.11.1 | No | Yes | New node version is greater than current version |
|
|
| 1.11.0 | 1.11.0-release.1 | No | No | New node version is less than current version |
|
|
| 1.11.0+release.1 | 1.11.0+release.2 | Yes | No | `release.1` and `release.2` are build metadata and ignored when comparing versions |
|
|
| 1.11.0-release.1+123 | 1.11.0-release.1+456 | Yes | No | Versions are equal, build metadata is ignored. |
|