mirror of
https://github.com/hashicorp/vault.git
synced 2025-08-07 15:17:03 +02:00
200 lines
7.3 KiB
Plaintext
200 lines
7.3 KiB
Plaintext
---
|
||
layout: docs
|
||
page_title: Upgrading Plugins - Guides
|
||
description: These are general upgrade instructions for Vault plugins.
|
||
---
|
||
|
||
# Upgrading Vault plugins
|
||
|
||
## Plugin upgrade procedure
|
||
|
||
The following procedures detail steps for upgrading a plugin that has been mounted
|
||
at a path on a running server. The steps are the same whether the plugin being
|
||
upgraded is built-in or external.
|
||
|
||
~> [Plugin versioning](/vault/docs/plugins#plugin-versioning) was introduced
|
||
with Vault 1.12.0, so if your Vault server is on 1.11.x or earlier, see the
|
||
[1.11.x version of this page](/vault/docs/v1.11.x/upgrading/plugins)
|
||
for plugin upgrade instructions.
|
||
|
||
### Upgrading auth and secrets plugins
|
||
|
||
The process is nearly identical for auth and secret plugins. If you are upgrading
|
||
an auth plugin, just replace all usages of `secrets` or `secret` with `auth`.
|
||
|
||
1. [Register][plugin_registration] the first version of your plugin to the catalog.
|
||
Skip this step if your initial plugin is built-in or already registered.
|
||
|
||
```shell-session
|
||
$ vault plugin register \
|
||
-sha256=<SHA256 Hex value of the plugin binary> \
|
||
secret \
|
||
my-secret-plugin
|
||
Success! Registered plugin: my-secret-plugin
|
||
```
|
||
|
||
1. [Mount][plugin_management] the plugin. Skip this step if your initial plugin
|
||
is already mounted.
|
||
|
||
```shell-session
|
||
$ vault secrets enable my-secret-plugin
|
||
Success! Enabled the my-secret-plugin secrets engine at: my-secret-plugin/
|
||
```
|
||
|
||
1. Register a second version of your plugin. You **must** use the same plugin
|
||
type and name (the last two arguments) as the plugin being upgraded. This is
|
||
true regardless of whether the plugin being upgraded is built-in or external.
|
||
|
||
```shell-session
|
||
$ vault plugin register \
|
||
-sha256=<SHA256 Hex value of the plugin binary> \
|
||
-command=my-secret-plugin-1.0.1 \
|
||
-version=v1.0.1 \
|
||
secret \
|
||
my-secret-plugin
|
||
Success! Registered plugin: my-secret-plugin
|
||
```
|
||
|
||
1. Set the new version as the cluster's pinned version.
|
||
|
||
```shell-session
|
||
$ vault write sys/plugins/pins/secret/my-secret-plugin version=v1.0.1
|
||
```
|
||
|
||
1. Trigger a global [plugin reload](/vault/docs/commands/plugin/reload) to
|
||
reload all instances of the plugin.
|
||
|
||
```shell-session
|
||
$ vault plugin reload -type=secret -plugin=my-secret-plugin -scope=global
|
||
Success! Reloading plugin: my-secret-plugin, reload_id: 98b1e875-4217-745d-07f2-93d14219fb3c
|
||
```
|
||
|
||
1. **Optional:** Check the "Running Version" field to verify the new version is
|
||
running:
|
||
|
||
```shell-session
|
||
$ vault secrets list -detailed
|
||
```
|
||
|
||
Until the reload step, the mount will still run the first version of `my-secret-plugin`. When
|
||
the reload is triggered, Vault will kill `my-secret-plugin`’s process and start the
|
||
new plugin process for `my-secret-plugin` version 1.0.1.
|
||
|
||
### Upgrading database plugins
|
||
|
||
1. [Register][plugin_registration] the first version of your plugin to the catalog.
|
||
Skip this step if your initial plugin is built-in or already registered.
|
||
|
||
```shell-session
|
||
$ vault plugin register
|
||
-sha256=<SHA256 Hex value of the plugin binary> \
|
||
database \
|
||
my-db-plugin
|
||
Success! Registered plugin: my-db-plugin
|
||
```
|
||
|
||
1. [Mount][plugin_management] the plugin. Skip this step if your initial plugin
|
||
is already mounted.
|
||
|
||
```shell-session
|
||
$ vault secrets enable database
|
||
$ vault write database/config/my-db \
|
||
plugin_name=my-db-plugin \
|
||
# ...
|
||
Success! Data written to: database/config/my-db
|
||
```
|
||
|
||
1. Register a second version of your plugin. You **must** use the same plugin
|
||
type and name (the last two arguments) as the plugin being upgraded. This is
|
||
true regardless of whether the plugin being upgraded is built-in or external.
|
||
|
||
```shell-session
|
||
$ vault plugin register \
|
||
-sha256=<SHA256 Hex value of the plugin binary> \
|
||
-command=my-db-plugin-1.0.1 \
|
||
-version=v1.0.1 \
|
||
database \
|
||
my-db-plugin
|
||
Success! Registered plugin: my-db-plugin
|
||
```
|
||
|
||
1. Set the new version as the cluster's pinned version.
|
||
|
||
```shell-session
|
||
$ vault write sys/plugins/pins/database/my-db-plugin version=v1.0.1
|
||
```
|
||
|
||
1. Trigger a global [plugin reload](/vault/docs/commands/plugin/reload) to
|
||
reload all instances of the plugin.
|
||
|
||
```shell-session
|
||
$ vault plugin reload -type=database -plugin=my-db-plugin -scope=global
|
||
Success! Reloading plugin: my-db-plugin, reload_id: 98b1e875-4217-745d-07f2-93d14219fb3c
|
||
```
|
||
|
||
1. **Optional:** Verify the current version of the running plugin:
|
||
|
||
```shell-session
|
||
$ vault read database/config/my-db
|
||
```
|
||
|
||
Until the reload step, the mount will still run the first version of `my-db-plugin`. When
|
||
the reload is triggered, Vault will kill `my-db-plugin`’s process and start the
|
||
new plugin process for `my-db-plugin` version 1.0.1.
|
||
|
||
### Downgrading plugins
|
||
|
||
Plugin downgrades follow the same procedure as upgrades. You can use the Vault
|
||
plugin list command to check what plugin versions are available to downgrade to:
|
||
|
||
```shell-session
|
||
$ vault plugin list secret
|
||
Name Version
|
||
---- -------
|
||
ad v0.14.0+builtin
|
||
alicloud v0.13.0+builtin
|
||
aws v1.12.0+builtin.vault
|
||
azure v0.14.0+builtin
|
||
cassandra v1.12.0+builtin.vault
|
||
consul v1.12.0+builtin.vault
|
||
gcp v0.14.0+builtin
|
||
gcpkms v0.13.0+builtin
|
||
kv v0.13.3+builtin
|
||
ldap v1.12.0+builtin.vault
|
||
mongodb v1.12.0+builtin.vault
|
||
mongodbatlas v0.8.0+builtin
|
||
mssql v1.12.0+builtin.vault
|
||
mysql v1.12.0+builtin.vault
|
||
nomad v1.12.0+builtin.vault
|
||
openldap v0.9.0+builtin
|
||
pki v1.12.0+builtin.vault
|
||
postgresql v1.12.0+builtin.vault
|
||
rabbitmq v1.12.0+builtin.vault
|
||
ssh v1.12.0+builtin.vault
|
||
terraform v0.6.0+builtin
|
||
totp v1.12.0+builtin.vault
|
||
transit v1.12.0+builtin.vault
|
||
```
|
||
|
||
### Additional upgrade notes
|
||
|
||
* As mentioned earlier, disabling existing mounts will wipe the existing data.
|
||
* Overwriting an existing version in the catalog will affect all uses of that
|
||
plugin version. So if you have 5 different Azure Secrets mounts using v1.0.0,
|
||
they'll all start using the new binary if you overwrite it. We recommend
|
||
treating plugin versions in the catalog as immutable, much like version control
|
||
tags.
|
||
* Each plugin has its own data within Vault storage. While it is rare for HashiCorp
|
||
maintained plugins to update their storage schema, it is up to plugin authors
|
||
to manage schema upgrades and downgrades. Check the plugin release notes for
|
||
any unsupported upgrade or downgrade transitions, especially before moving to
|
||
a new major version or downgrading.
|
||
* Existing Vault [leases](/vault/docs/concepts/lease) and [tokens](/vault/docs/concepts/tokens)
|
||
are generally unaffected by plugin upgrades and reloads. This is because the lifecycle
|
||
of leases and tokens is handled by core systems within Vault. The plugin itself only
|
||
handles renewal and revocation of them when it’s requested by those core systems.
|
||
|
||
[plugin_reload_api]: /vault/api-docs/system/plugins-reload
|
||
[plugin_registration]: /vault/docs/plugins/plugin-architecture#plugin-registration
|
||
[plugin_management]: /vault/docs/plugins/plugin-management#enabling-disabling-external-plugins
|