Vault
Register and enable external plugins
An external plugin is any authentication or secrets plugin build from external
code. Vault pre-registers commonly used external plugins (like kv
), but you
must manually add other external plugins to the Vault plugin catalog before you
can use them with your Vault installation.
If you register an external plugin with the same name as a pre-registered plugin, Vault defaults to the manually registered plugin when you enable a new mount with that name.
Before you start
- To register enterprise plugins, you have Vault v1.16.21+, 1.17.17+, 1.18.10+, or 1.19.4+.
- You must have admin permissions for Vault. Specifically, you must be able
to run
plugin register
and the appropriateenable
command. - You must have
plugin_directory
set in your Vault configuration file. - For enterprise plugins, you must have the plugin
.zip
file extracted to the expected location insideplugin_directory
. For example,vault-plugin-database-oracle_0.11.0+ent_linux_amd64.zip
must be extracted to<plugin_directory>/vault-plugin-database-oracle_0.11.0+ent_linux_amd64/
. - For other plugins, you must have the plugin binary saved to the
location set in
plugin_directory
. - You must have
api_addr
set in your Vault configuration file.
See Recommendation to register enterprise plugins on Vault v1.16.17 - v1.16.20, v1.17.13 - v1.17.16, v1.18.6 - v1.18.9, or v1.19.0 - v1.19.3.
Step 1: Update the plugin catalog
You must register your external plugin with the Vault catalog before enabling it. Registering plugins ensures the plugin invoked by Vault is authentic and maintains integrity.
Enterprise
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 asmykvplugin
:$ vault plugin register \ -command mykvplugin \ -sha256 ${PLUGIN_SHA} \ -version "v1.0.1" \ secret \ mykv Success! Registered plugin: mykv
Step 2: Enable the plugin
Enable the plugin to make it available to clients.
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/
Step 3: Verify the plugin status
Verify the plugin is ready for use and running the correct version.
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)