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.

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 the first version of your plugin to the catalog. Skip this step if your initial plugin is built-in or already registered.

   $ vault plugin register \
       -sha256=<SHA256 Hex value of the plugin binary> \
       secret \
       my-secret-plugin
   Success! Registered plugin: my-secret-plugin
   

   Copy

2. Mount the plugin. Skip this step if your initial plugin is already mounted.

   $ vault secrets enable my-secret-plugin
   Success! Enabled the my-secret-plugin secrets engine at: my-secret-plugin/
   

   Copy

3. 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.

   $ 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
   

   Copy

4. Set the new version as the cluster's pinned version.

   $ vault write sys/plugins/pins/secret/my-secret-plugin version=v1.0.1
   

   Copy

5. Trigger a global plugin reload to reload all instances of the plugin.

   $ vault plugin reload -type=secret -plugin=my-secret-plugin -scope=global
   Success! Reloading plugin: my-secret-plugin, reload_id: 98b1e875-4217-745d-07f2-93d14219fb3c
   

   Copy

6. Optional: Check the "Running Version" field to verify the new version is running:

   $ vault secrets list -detailed
   

   Copy

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 the first version of your plugin to the catalog. Skip this step if your initial plugin is built-in or already registered.

   $ vault plugin register
       -sha256=<SHA256 Hex value of the plugin binary> \
       database \
       my-db-plugin
   Success! Registered plugin: my-db-plugin
   

   Copy

2. Mount the plugin. Skip this step if your initial plugin is already mounted.

   $ vault secrets enable database
   $ vault write database/config/my-db \
       plugin_name=my-db-plugin \
       # ...
   Success! Data written to: database/config/my-db
   

   Copy

3. 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.

   $ 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
   

   Copy

4. Set the new version as the cluster's pinned version.

   $ vault write sys/plugins/pins/database/my-db-plugin version=v1.0.1
   

   Copy

5. Trigger a global plugin reload to reload all instances of the plugin.

   $ vault plugin reload -type=database -plugin=my-db-plugin -scope=global
   Success! Reloading plugin: my-db-plugin, reload_id: 98b1e875-4217-745d-07f2-93d14219fb3c
   

   Copy

6. Optional: Verify the current version of the running plugin:

   $ vault read database/config/my-db
   

   Copy

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:

$ 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 and 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.