| --- |
| 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 |
| ``` |
| |
| 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](/vault/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. |
| * 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-backend |
| [plugin_registration]: /vault/docs/plugins/plugin-architecture#plugin-registration |
| [plugin_management]: /vault/docs/plugins/plugin-management#enabling-disabling-external-plugins |