vault/website/content/docs/upgrading/plugins.mdx

200 lines
7.3 KiB
Plaintext
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

---
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 its 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