185 lines
6.8 KiB
Plaintext
185 lines
6.8 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 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](/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
|
||
```
|
||
|
||
1. [Mount][plugin_management] the plugin. Skip this step if your initial plugin
|
||
is already mounted.
|
||
|
||
```shell-session
|
||
$ vault secrets enable 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
|
||
```
|
||
|
||
1. Tune the existing mount to configure it to use the newly registered version.
|
||
|
||
```shell-session
|
||
$ vault secrets tune -plugin-version=v1.0.1 my-secret-plugin
|
||
```
|
||
|
||
1. If you wish, you can check the updated configuration. Notice the "Version" is
|
||
now different from the "Running Version".
|
||
|
||
```shell-session
|
||
$ vault secrets list -detailed
|
||
```
|
||
|
||
1. Finally, trigger a [plugin reload](/docs/commands/plugin/reload) to reload all
|
||
mounted backends using that plugin or a subset of the mounts using that plugin
|
||
with either the `plugin` or `mounts` flag respectively.
|
||
|
||
```shell-session
|
||
$ vault plugin reload -plugin my-secret-plugin
|
||
```
|
||
|
||
Until the last 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. The "Running Version" should also
|
||
now match the "Version" when you run `vault secrets list -detailed`.
|
||
|
||
-> **Important:** Plugin reload of a new plugin binary must be
|
||
performed on each Vault instance. Performing a plugin upgrade on a single
|
||
instance or through a load balancer can result in mismatched
|
||
plugin binaries within a cluster. On a replicated cluster this may be accomplished
|
||
by setting the 'scope' parameter of the reload to 'global'.
|
||
|
||
### 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
|
||
```
|
||
|
||
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 \
|
||
# ...
|
||
```
|
||
|
||
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
|
||
```
|
||
|
||
1. Update the database config with the new version. The database secrets
|
||
engine will immediately reload the plugin, using the new version. Any omitted
|
||
config parameters will not be updated.
|
||
|
||
```shell-session
|
||
$ vault write database/config/my-db \
|
||
plugin_version=v1.0.1
|
||
```
|
||
|
||
Until the last 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.
|
||
|
||
[plugin_reload_api]: /api-docs/system/plugins-reload-backend
|
||
[plugin_registration]: /docs/plugins/plugin-architecture#plugin-registration
|
||
[plugin_management]: /docs/plugins/plugin-management#enabling-disabling-external-plugins
|