--- layout: docs page_title: Upgrading Plugins - Guides description: These are general upgrade instructions for Vault plugins. --- # Upgrading Vault Plugins ## External Plugin Upgrade Procedure The following procedure details steps for upgrading an external plugin that has been registered to the catalog on a running server. This procedure is applicable to secret engines, auth methods, and database plugins. Vault executes plugin binaries when they are configured and roles are established around them. The binary cannot be modified or replaced while running, so upgrades cannot be performed by simply swapping the binary and updating the hash in the plugin catalog. Instead, you can restart or reload a plugin with the `sys/plugins/reload/backend` [API][plugin_reload_api]. Follow these steps to replace or upgrade a Vault plugin binary: 1. [Register][plugin_registration] version 1 of `my-db-plugin` to the catalog. Skip this step if your plugin is already registered. ```shell-session $ vault plugin register -sha256= \ database \ # type my-db-plugin ``` 2. [Mount][plugin_management] the plugin backend. Skip this step if the backend is already mounted. ```shell-session $ vault secrets enable database ``` 3. Register version 2 of `my-db-plugin` to the catalog under the same plugin name, but with updated command to run version 2 of `my-db-plugin` and updated sha256 of the new binary ```shell-session $ vault plugin register -sha256= \ database \ # type my-db-plugin ``` 4. 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` parameter respectively. ```shell-session $ vault plugin reload -plugin my-db-plugin ``` Until step 4, the mount will still use version 1 of `my-db-plugin`, and when the reload is triggered, Vault will kill `my-db-plugin`’s process and start the new plugin process for `my-db-plugin` version 2. -> **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'. ## Overriding Built-in Plugins ### Background Vault's auth methods and secrets engines are structured as plugins, but this design is not obvious since many of them are built into Vault. You can see them with the Vault plugin list command, for example, the list of Secrets engines: ```shell-session $ vault plugin list secret Plugins ------- ad alicloud aws azure cassandra consul gcp gcpkms kv mongodb mongodbatlas mssql mysql nomad openldap pki postgresql rabbitmq ssh terraform totp transit ``` This will list all Secrets engines, internal (built-in) or external. To find out if a plugin is built-in, we can query its info: ```shell-session $ vault plugin info secret azure Key Value --- ----- args [] builtin true command n/a name azure sha256 n/a ``` Because these built-in engines are plugins, they can be overridden. This can be a useful way to leverage features or bug fixes in plugins that are newer than the version of Vault you're using, without updating or even restarting Vault, and while retaining the data for your existing mount. Assume you have a new version of Azure Secrets and the binary is called "azure_new". The binary needs to be in the [plugin directory](/docs/plugins/plugin-architecture#plugin-directory) and can then be registered as either a distinct plugin, or overriding the current one. ~> **Important:** do not disable (`vault secrets disable ...`) any mount that has data you're interested in; that would erase storage. For the in-place update, register a new plugin atop the built-in one and leave any mounts alone. ### Procedure for Overriding Built-in Plugins The syntax is the same as an external plugin, with the difference being you name it the same as a built-in: ```shell-session $ vault plugin register \ -sha256= \ -command=azure_new \ secret \ azure ``` "-command=azure_new" is the name of the binary, "secret" is the plugin type, and "azure" is the name of the built-in plugin that we're overriding. We can verify that the override is in place: ```shell-session $ vault plugin info secret azure Key Value --- ----- args [] builtin false command azure_new name azure sha256 f6f6ec45d37484c257aa9ff80444b9f244aaef1c650edf8a42a2a1d3f00db2c5 ``` At this point we've overridden the built-in, but it is not yet actively handling requests. For that we run: ```shell-session $ vault plugin reload -plugin=azure ``` ### Procedure for Reverting After Overriding A Built-in Plugin To revert the override, first deregister the plugin: ```shell-session $ vault plugin deregister secret azure ``` Next, verify the override has been reverted and we are now using the built-in plugin: ```shell-session $ vault plugin info secret azure Key Value --- ----- args [] builtin true command n/a name azure sha256 n/a ``` Finally, reload the plugin: ```shell-session $ vault plugin reload -plugin=azure ``` ### Caveats to Overriding Built-in Plugins * As mentioned earlier, disabling existing mounts will wipe the existing data. * This type of upgrade affects all uses of the plugin. So if you have 5 different Azure Secrets mounts, they'll all change after the replacement. If you don't want that, you'll need to register the plugin under a different name and start with a fresh mount. * In most cases, data upgrade and downgrade is not an issue. If the "new" version introduces new data and you downgrade, the "old" version will ignore the extraneous data. In some cases upgrading changes existing data in non-backwards compatible ways, so it is good to check whether this is an issue. [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