Upgrade plugins

Upgrading a plugin in the catalog affects all uses of that plugin version. For example, if you have 5 different customkv mounts using v1.0.0 and you upgrade to v1.1.0, all the existing mounts will use the new binary if you overwrite it. We recommend treating plugin versions in the catalog as immutable, like version control tags, rather than overwriting them explicitly.

Always check the plugin release notes for unsupported transitions before upgrading your plugins. Core systems within Vault manage the token and lease lifecycle so plugins only renew or revoke tokens and leases when the core systems requests it. As a result, existing tokens and leases are generally unaffected by plugin upgrades.

Before you start

To register and upgrade enterprise plugins, you must have Vault v1.16.16+, 1.17.12+, 1.18.5+, or 1.19.x+.
You must have admin permissions for Vault. Specifically, you must be able to run plugin register and the appropriate enable command.
You must have plugin_directory set in your Vault configuration file.
You must have the new plugin binary or zip file saved to the location set in plugin_directory.
You must have api_addr set in your Vault configuration file.

Step 1: Update the catalog entry

Register the new plugin binary or zip file with an updated version number under the same plugin type and name as the existing plugin version.

Enterprise plugins must be compatible with the system that runs Vault and saved to the plugin directory unzipped with the name provided on the HashiCorp releases page. Vault Enterprise verifies plugin integrity, checks system compatibility, and unzips the plugin artifact during the registration process.

Save the SHA for your plugin binary:

$ PLUGIN_SHA=$(sha256sum <path_to_plugin_binary> | awk '{print $1;}')

Use vault plugin register to add your plugin to the catalog:

$ vault plugin register                     \
    -command <command_to_run_plugin_binary> \
    -sha256 "${PLUGIN_SHA[0]}"              \
    -version "<semantic_version>"           \
    <plugin_type>                           \
    <plugin_name>                           \

For example, to register a secrets plugin called mykv that runs on the command line as mykvplugin:

$ vault plugin register   \
    -command mykvplugin   \
    -sha256 ${PLUGIN_SHA} \
    -version "v1.0.1"     \
    secret                \
    mykv

Success! Registered plugin: mykv

Save the SHA, version, and run command for your plugin binary to a JSON file:

$ cat <<-EOF > data.json
{
  "sha256": "$(sha256sum <path_to_plugin_binary> | awk '{print $1;}')",
  "command": "<command_to_run_plugin_binary>",
  "version": "<semantic_version>"
}
EOF

For example, to create a data file for a plugin that runs on the command line as mykvplugin:

$ cat <<-EOF > data.json
{
  "sha256": "$(sha256sum mykvplugin | awk '{print $1;}')",
  "command": "mykvplugin",
  "version": "v1.0.1"
}
EOF

Call the RegisterPlugin endpoint to add your plugin to the catalog:

$ curl                                      \
  --request POST                            \
  --header "X-Vault-Token: ${VAULT_TOKEN}"  \
  --data @data.json                         \
  ${VAULT_ADDR}/v1/sys/plugins/catalog/<plugin_type>/<plugin_name>

For example, to register a secrets plugin called mykv:

$ curl                                      \
  --request POST                            \
  --header "X-Vault-Token: ${VAULT_TOKEN}"  \
  --data @data.json                         \
  ${VAULT_ADDR}/v1/sys/plugins/catalog/secret/mykv

Call the ListPlugins endpoint to verify registration:

$ curl                                      \
  --request GET                             \
  --header "X-Vault-Token: ${VAULT_TOKEN}"  \
  ${VAULT_ADDR}/v1/sys/plugins/catalog      \
  | jq '.data.detailed | .[] | select(.name =="mykv")'

For example:

$ curl                                      \
  --request GET                             \
  --header "X-Vault-Token: ${VAULT_TOKEN}"  \
  ${VAULT_ADDR}/v1/sys/plugins/catalog      \
  | jq '.data.detailed | .[] | select(.name =="mykv")'

{
  "builtin": false,
  "name": "mykv",
  "sha256": "4b7c6993b7147d84d958f30438f9d0c34f34aa400300693b193e62774e4338d7",
  "type": "secret",
  "version": "v1.0.1"
}

Step 2: Reload the plugin

Until you reload the plugin, Vault continues running the old plugin version on the mount path. When you trigger a reload, Vault kills the active plugin process and start a new plugin process with the pinned version of that plugin.

Call vault write with the /sys/plugins/pins/{type}/{name} endpoint path to pin the new plugin version for the current cluster. You must explicitly call the endpoint from the root namespace or Vault returns an 404: unsupported path error:

$ vault write                                                      \
    -namespace root                                                \
    /sys/plugins/pins/<secret | auth | database>/<registered_name> \
    version="<semantic_version>"

For example, to pin a secrets plugin called mykv to version 1.0.0:

$ vault write                    \
    -namespace root              \
    sys/plugins/pins/secret/mykv \
    version="v1.0.0"

Call vault plugin reload to trigger a global refresh for all instances of the downgraded plugin:

$ vault plugin reload                \
    -type <secret | auth | database> \
    -plugin <registered_plugin_name> \
    -scope global

For example, to refresh the mykv plugin:

$ vault plugin reload \
    -type secret      \
    -plugin mykv      \
    -scope global

Success! Reloading plugin: mykv, reload_id: 1b7e989a-e1f9-2047-d41c-307ce64194e9

Call the SetPinnedVersion endpoint to pin the new plugin version for the current cluster:

 $ curl                                      \
   --request POST                            \
   --header "X-Vault-Token: ${VAULT_TOKEN}"  \
   --data '{"version":"<semantic_version>"}' \
   ${VAULT_ADDR}/v1/sys/plugins/pins/<plugin_type>/<plugin_name>

For example, to pin a secrets plugin called mykv to version 1.0.1:

$ curl                                      \
  --request POST                            \
  --header "X-Vault-Token: ${VAULT_TOKEN}"  \
  --data '{"version":"v1.0.1"}'             \
  ${VAULT_ADDR}/v1/sys/plugins/pins/secret/mykv | jq

{
    "request_id": "f81013b1-e324-215c-07c6-f66b5b6fdc56",
    "lease_id": "",
    "renewable": false,
    "lease_duration": 0,
    "data": null,
    "wrap_info": null,
    "warnings": null,
    "auth": null,
    "mount_type": "system"
}

Call the ReloadPlugins endpoint to trigger a global refresh for all instances of the downgraded plugin:

$ curl                                     \
  --request POST                           \
  --header "X-Vault-Token: ${VAULT_TOKEN}" \
  --data '{"scope":"global"}'              \
  ${VAULT_ADDR}/v1/sys/plugins/reload/<plugin_type>/<plugin_name>

For example, to refresh the mykv plugin:

$ curl                                     \
  --request POST                           \
  --header "X-Vault-Token: ${VAULT_TOKEN}" \
  --data '{"scope":"global"}'              \
  ${VAULT_ADDR}/v1/sys/plugins/reload/secret/mykv | jq
{
"request_id": "1b543f61-22a3-bfe9-d182-50ce75459373",
"lease_id": "",
"renewable": false,
"lease_duration": 0,
"data": {
    "reload_id": "1b543f61-22a3-bfe9-d182-50ce75459373"
},
"wrap_info": null,
"warnings": null,
"auth": null,
"mount_type": ""
}

Step 3: Verify the plugin status

Use the appropriate list command (vault secrets list or vault auth list) to verify the version and mounted path for the registered plugin:

$ vault <secrets | auth> list

For example, to verify the mykv plugin:

$ vault secrets list

Path            Type            Accessor                 Description
----            ----            --------                 -----------
cubbyhole/      ns_cubbyhole    ns_cubbyhole_dd6729a7    per-token private secret storage
custom/mykv/    mykv            mykv_7121a3d5            n/a
identity/       ns_identity     ns_identity_f000c24d     identity store
private/        kv              kv_4a4118d8              n/a
shared/         kv              kv_60208c6d              n/a
sys/            ns_system       ns_system_b9a3364f       system endpoints used for control, policy and debugging

The list subcommand does not support filtering for specific fields in the output, to confirm the version or running version, use the -detailed flag, filter for the relevant plugin, and print the desired status column by index:

Index	Detail column
0	Path
1	Plugin
2	Accessor
3	Default TTL
4	Max TTL
5	Force No Cache
6	Replication
7	Seal Wrap
8	External Entropy Access
9	Options
10	Description
11	UUID
12	Version
13	Running Version
14	Running SHA256
15	Deprecation Status

For example, to print the running version for mykv:

$ row=($(vault secrets list -detailed | grep mykv)) ; \
  echo "${row[0]}: ${row[1]} (${row[13]})"

custom/mykv/: mykv (v1.0.1)

Use the appropriate list endpoint (ListSecretsEngines or ListAuthMethods) to verify the mounted path for the registered plugin:

$ curl -s                                          \
  --request GET                                    \
  --header "X-Vault-Token: ${VAULT_TOKEN}"         \
  --header "X-Vault-Namespace: ${VAULT_NAMESPACE}" \
  ${VAULT_ADDR}/v1/sys/<mounts | auth> | jq '.data."<mount_path>"'

For example, to verify the mykv secrets plugin on the path /custom/kv:

$ curl -s                                          \
  --request GET                                    \
  --header "X-Vault-Token: ${VAULT_TOKEN}"         \
  --header "X-Vault-Namespace: ${VAULT_NAMESPACE}" \
  ${VAULT_ADDR}/v1/sys/mounts | jq '.data."custom/mykv/"'

{
  "accessor": "mykv_7121a3d5",
  "config": {
    "default_lease_ttl": 0,
    "force_no_cache": false,
    "max_lease_ttl": 0
  },
  "description": "",
  "external_entropy_access": false,
  "local": false,
  "options": {},
  "plugin_version": "v1.0.1",
  "running_plugin_version": "v1.0.1",
  "running_sha256": "4b7c6993b7147d84d958f30438f9d0c34f34aa400300693b193e62774e4338d7",
  "seal_wrap": false,
  "type": "mykv",
  "uuid": "61c79aea-5b39-1cbb-b470-96edd9f6bfeb"
}