vault/website/content/docs/plugins/index.mdx

---
layout: docs
page_title: Plugin ecosystem
description: >- 
   Learn about the plugin ecosystem and the difference between built-in and
   external plugins.
---

> [!IMPORTANT]  
> **Documentation Update:** Product documentation, which were located in this repository under `/website`, are now located in [`hashicorp/web-unified-docs`](https://github.com/hashicorp/web-unified-docs), colocated with all other product documentation. Contributions to this content should be done in the `web-unified-docs` repo, and not this one. Changes made to `/website` content in this repo will not be reflected on the developer.hashicorp.com website.


# 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](/vault/docs/plugins/upgrade) 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](https://github.com/hashicorp/vault).
  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](/vault/docs/plugins/plugin-architecture#plugin-multiplexing)
to improve performance by reusing plugin instances across all mounts of a given
type.

@include 'tips/get-plugins.mdx'


## 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](https://releases.hashicorp.com/) or build community
  plugins
  [from source code](/vault/docs/plugins/plugin-development#building-a-plugin-from-source).
- You can download containerized plugins from the
  [HashiCorp Docker Registry](https://hub.docker.com/u/hashicorp) or
  [HashiCorp AWS Elastic Container Registry (ECR)](https://gallery.ecr.aws/hashicorp),
  or [containerize the plugin source code yourself](/vault/docs/plugins/containerized-plugins).


## Enterprise plugins

@include 'alerts/enterprise-and-hcp.mdx'

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](https://releases.hashicorp.com/).


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

```shell-session
$ 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.
1. Use the most recent semantic version registered in the plugin catalog.
1. Ignore version if the version in the plugin catalog is unset or "n/a".


<Note title="Reserved word">

Vault reserves the `+builtin` metadata identifier for built-in plugins.
You cannot use the `+builtin` string when manually registering an external
plugin.

</Note>

## Tutorial

Refer to the [custom secrets engines](/vault/tutorials/custom-secrets-engine)
tutorials to build a custom secrets engine to rotate your own tokens, passwords,
and more with Vault.