mirror of
https://github.com/hashicorp/vault.git
synced 2025-08-15 02:57:04 +02:00
96 lines
4.0 KiB
Plaintext
96 lines
4.0 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: Plugin System
|
|
description: Learn about Vault's plugin system.
|
|
---
|
|
|
|
|
|
# Plugin system
|
|
|
|
Vault supports 3 types of plugins; auth methods, secret engines, and database
|
|
plugins. This concept allows both built-in and external plugins to be treated
|
|
like building blocks. Any plugin can exist at multiple different mount paths.
|
|
Different versions of a plugin may be at each location, with each version differing
|
|
from Vault's version.
|
|
|
|
A plugin is uniquely identified by its type (one of `secret`, `auth`, or
|
|
`database`), name (e.g. `aws`), and version (e.g `v1.0.0`). An empty version
|
|
implies either the built-in plugin or the single unversioned plugin that can
|
|
be registered.
|
|
|
|
See [Plugin Upgrade Procedure](/vault/docs/upgrading/plugins#plugin-upgrade-procedure)
|
|
for details on how to upgrade a built-in plugin in-place.
|
|
|
|
## Built-In plugins
|
|
|
|
Built-in plugins are shipped with Vault, often for commonly used integrations,
|
|
and can be used without any prerequisite steps.
|
|
|
|
## External plugins
|
|
|
|
External plugins are not shipped with Vault and require additional operator
|
|
intervention to run.
|
|
|
|
To run an external plugin, a binary or container image of the plugin is required. Plugin
|
|
binaries can be obtained from [releases.hashicorp.com](https://releases.hashicorp.com/)
|
|
or they can be [built from source](/vault/docs/plugins/plugin-development#building-a-plugin-from-source).
|
|
Containerized plugins are not yet available from a registry and must currently
|
|
be built.
|
|
|
|
Vault's external plugins are completely separate, standalone applications that
|
|
Vault executes and communicates with over RPC. Each time a Vault secret engine,
|
|
auth method, or database plugin is mounted, a new process or container is spawned. However,
|
|
plugins can be made to implement [plugin multiplexing](/vault/docs/plugins/plugin-architecture#plugin-multiplexing)
|
|
to improve performance. Plugin multiplexing allows plugin instances to be
|
|
reused across all mounts of a given type.
|
|
|
|
-> **NOTE:** See the [Vault Integrations](/vault/integrations) page to find a
|
|
curated collection of official, partner, and community Vault plugins.
|
|
|
|
## Plugin versioning
|
|
|
|
Vault supports managing, running and upgrading plugins using semantic version
|
|
information.
|
|
|
|
The plugin catalog optionally supports specifying a semantic version when
|
|
registering an external plugin. Multiple versions of a plugin can be registered
|
|
in the catalog simultaneously, and a version can be selected when mounting a
|
|
plugin or tuning an existing mount in-place.
|
|
|
|
Alternatively, users can select pinned versions to enforce uniform cluster-wide
|
|
version selection. When a pinned version is in effect, versions cannot be
|
|
specified in mount config, and existing mounts that specify a version will
|
|
ignore the locally configured version. See the
|
|
[pinned versions](/vault/api-docs/system/plugins-pins) API for more details.
|
|
|
|
If no version is specified when creating a new mount, the following precedence is used
|
|
for any available plugins whose type and name match:
|
|
|
|
1. The pinned version of the plugin, if any exists.
|
|
1. The plugin registered with no version.
|
|
1. The plugin with the most recent semantic version among any registered versions.
|
|
1. The plugin built into Vault.
|
|
|
|
### Built-In versions
|
|
|
|
Vault will report a version for built-in plugins to indicate what version of the
|
|
plugin code got built into Vault as a dependency. For example:
|
|
|
|
```shell-session
|
|
$ vault plugin list secret
|
|
Name Version
|
|
---- -------
|
|
ad v0.14.0+builtin
|
|
alicloud v0.13.0+builtin
|
|
aws v1.12.0+builtin.vault
|
|
# ...
|
|
```
|
|
|
|
Here, Vault has a dependency on `v0.14.0` of the [hashicorp/vault-plugin-secrets-ad](https://github.com/hashicorp/vault-plugin-secrets-ad)
|
|
repo, and the `vault` metadata identifier for `aws` indicates that plugin's code was
|
|
within the Vault repo. For plugins within the Vault repo, Vault's own major, minor,
|
|
and patch versions are used to form the plugin version.
|
|
|
|
The `builtin` metadata identifier is reserved and cannot be used when registering
|
|
external plugins.
|