Register and enable external plugins

1. Save the SHA for your plugin binary:

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

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

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

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

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

Use the appropriate enable command (vault secrets enable or vault auth enable) and the registered name to mount the external plugin:

$ vault <secrets | auth> enable \
  -path <mount_path>            \
  <plugin_name>

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

$ vault secrets enable \
  -path custom/kv      \
  mykv

Success! Enabled the mykv secrets engine at: custom/kv/

1. Save the type and any relevant configuration details to a JSON file:

   $ cat <<-EOF > data.json
   {
     "type": "<registered_plugin_name>",
     "config": {
       "plugin_version": "<semantic_version>"
     }
   }
   EOF
   

   For example, to create a data file for the mykv plugin:

   $ cat <<-EOF > data.json
   {
     "type": "mykv",
     "config": {
       "plugin_version": "v1.0.0"
     }
   }
   EOF
   

2. Use the appropriate enable endpoint ( EnableSecretsEngine or EnableAuthMethod) and the registered plugin name to mount the external plugin:

   $ curl                                             \
     --request POST                                   \
     --header "X-Vault-Token: ${VAULT_TOKEN}"         \
     --header "X-Vault-Namespace: ${VAULT_NAMESPACE}" \
     --data @data                                     \
     ${VAULT_ADDR}/v1/sys/<mounts | auth>/<mount_path>
   

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

   $ curl                                              \
     --request POST                                    \
     --header "X-Vault-Token: ${VAULT_TOKEN}"          \
     --header "X-Vault-Namespace: ${VAULT_NAMESPACE}"  \
     --data @data                                      \
     ${VAULT_ADDR}/v1/sys/mounts/custom/kv
   

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:

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"
}