scottk/vault
1
0
Fork 0
mirror of https://github.com/optim-enterprises-bv/vault.git synced 2025-11-01 19:17:58 +00:00
Code Issues Packages Projects Releases Wiki Activity

Docs: Plugin versioning documentation (#17460)

Browse Source 
Co-authored-by: John-Michael Faircloth <fairclothjm@users.noreply.github.com>
This commit is contained in:
Tom Proctor
2022-10-11 23:12:02 +01:00
committed by GitHub
parent 11e7f1c624
commit 8bf0866164
15 changed files with 433 additions and 262 deletions
Download Patch File Download Diff File Expand all files Collapse all files

73
website/content/docs/plugins/index.mdx
View File

@@ -7,21 +7,24 @@ description: Learn about Vault's plugin system.
# Plugin System
All Vault auth methods and secrets engines are considered 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.
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](/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 implementations,
and require no additional operator intervention to run. Built-in plugins are
just like any other backend code inside Vault.
To use a different or edited version of a built-in plugin, the plugin must be
run as an external plugin. See [Overriding Built-in Plugins](/docs/upgrading/plugins#overriding-built-in-plugins)
for details on how to override a built-in plugin in-place.
Built-in plugins are shipped with Vault, often for commonly used integrations,
and can be used without any prerequisite steps.
## External Plugins
@@ -33,8 +36,48 @@ binaries can be obtained from [releases.hashicorp.com](https://releases.hashicor
or they can be [built from source](/docs/plugins/plugin-development#building-a-plugin-from-source).
Vault's external plugins are completely separate, standalone applications that
Vault executes and communicates with over RPC. Each time a Vault secret engine
or auth method is mounted, a new process is spawned. However, plugins can be
made to implement [plugin multiplexing](/docs/plugins/plugin-architecture#plugin-multiplexing)
Vault executes and communicates with over RPC. Each time a Vault secret engine,
auth method, or database plugin is mounted, a new process is spawned. However,
plugins can be made to implement [plugin multiplexing](/docs/plugins/plugin-architecture#plugin-multiplexing)
to improve performance. Plugin multiplexing allows plugin processes to be
reused across all mounts of a given type.
## 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.
If no version is specified when creating a new mount, the following precedence is used
for any available plugins whose type and name match:
* The plugin registered with no version
* The plugin with the most recent semantic version among any registered versions
* 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.