The Vault plugin ecosystem

Plugins act as building blocks in Vault that help you control how data moves through your environment and how clients access that data.

Vault supports the following plugin types:

• auth plugins handle authentication flows and allow clients to authenticate to Vault.
• secret plugins act as secret engines that generate, store, and manage sensitive information.
• database plugins provide dynamic credentials that allow clients to access database data.

Clients access plugins on unique mount paths and you can run different versions of the same plugin at each location.

Vault uniquely identifies plugins based on its type, name, and version. Built-in plugin and single, unversioned plugins may leave version information unset.

Refer to the plugin upgrade guide for more information on upgrading plugins.

Plugin sources

Plugin code falls into one of the following categories:

• embedded plugins build from code maintained within the Vault repository on GitHub. HashiCorp develops and maintains all embedded plugins.
• discrete plugins build from code maintained independently from the Vault code. External plugins can be HashiCorp plugins, third-party plugins, or community plugins.
• custom plugins are discrete plugins built from specialized code either written from scratch or by modifying an existing plugin. Typically, custom plugins solve a specific, niche problem and are not publicly available.

Built-in vs external plugins

Plugins run within Vault as built-in or external plugins.

Vault ships with a set of built-in plugins for commonly used integrations. Vault preregisters built-in plugins and runs those plugins within the main Vault process. You can enable and use built-in plugins without manually registering them, regardless of whether the plugin build from an embedded or discrete source.

External plugins run as separate, standalone applications that Vault executes and communicates with over RPC. When you mount an external plugin, Vault spawns a new process or container to run the code. Vault also supports plugin multiplexing to improve performance by reusing plugin instances across all mounts of a given type.

Community plugins

You must have a binary or runnable container to register and run external, community plugins.

• You can download compiled binaries from the HashiCorp releases page or build community plugins from source code.
• You can download containerized plugins from the HashiCorp Docker Registry or HashiCorp AWS Elastic Container Registry (ECR), or containerize the plugin source code yourself.

Enterprise plugins

You must have the compiled binary or .zip to register and run external, Enterprise plugins. You can download Enterprise plugin artifacts from the HashiCorp releases page.

Plugin versioning

Vault supports semantic versioning for plugins. You can assign a semantic version when you register an external plugin and register multiple versions of the same plugin simultaneously. You can assign an explicit version when you mount a plugin and/or pin a default version to enforce uniform cluster-wide version selection. Pinning a version disallows explicit version selection in the configuration for a specific plugin mount. Embedded plugins compile as part of the Vault binary, so they always have the same version number as your Vault version.

Built-in plugin versions include tags to show whether the plugin was preregistered as an embedded plugin (+builtin.vault) or a discrete plugin (+builtin).

For example, in the following CLI output:

• azure is version 0.20.1 of a built-in, discrete plugin.
• aws is version 1.18.5 of a built-in, embedded plugin.
• mykv is version 1.0.0 of an external plugin.
• testkv is an unversioned external plugin.

$ vault plugin list secret
Name                   Version
----                   -------
aws                    v1.18.5+builtin.vault
azure                  v0.20.1+builtin
gcp                    v0.20.1+builtin
gcpkms                 v0.19.0+builtin
keymgmt                v0.13.0+builtin
kmip                   v0.16.1+builtin
kubernetes             v0.9.0+builtin
kv                     v0.20.0+builtin
ldap                   v1.18.5+builtin.vault
mongodbatlas           v0.13.0+builtin
mykv                   v1.0.0
nomad                  v1.18.5+builtin.vault
openldap               v0.14.5+builtin
pki                    v1.18.5+builtin.vault
rabbitmq               v1.18.5+builtin.vault
testkv                 n/a
ssh                    v1.18.5+builtin.vault
terraform              v0.10.0+builtin
testing/custom/mykv    v1.0.0
totp                   v1.18.5+builtin.vault
transform              v0.16.1+builtin
transit                v1.18.5+builtin.vault

New mounts for plugins adhere to the following precedence when determining the appropriate version:

1. Use the pinned version of the plugin, if it exists.
2. Use the most recent semantic version registered in the plugin catalog.
3. Ignore version if the version in the plugin catalog is unset or "n/a".

Tutorial

Refer to the custom secrets engines tutorials to build a custom secrets engine to rotate your own tokens, passwords, and more with Vault.