mirror of
https://github.com/hashicorp/vault.git
synced 2025-08-22 15:11:07 +02:00
0660ea6fac
* Update README Let contributors know that docs will now be located in UDR * Add comments to each mdx doc Comment has been added to all mdx docs that are not partials * chore: added changelog changelog check failure * wip: removed changelog * Fix content errors * Doc spacing * Update website/content/docs/deploy/kubernetes/vso/helm.mdx Co-authored-by: Tu Nguyen <im2nguyen@users.noreply.github.com> --------- Co-authored-by: jonathanfrappier <92055993+jonathanfrappier@users.noreply.github.com> Co-authored-by: Tu Nguyen <im2nguyen@users.noreply.github.com>
115 lines
5.3 KiB
Plaintext
115 lines
5.3 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: Plugin architecture
|
|
description: >-
|
|
Learn how plugin processes run and interact with Vault.
|
|
---
|
|
|
|
> [!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.
|
|
|
|
# Plugin architecture
|
|
|
|
Plugins are separate, standalone applications with have predefined interfaces
|
|
and parameters. Vault executes and communicates with plugins over RPC. Plugins
|
|
do not share memory space with Vault and a crash in the plugin cannot crash the
|
|
entirety of Vault.
|
|
|
|
|
|
## Plugin registration
|
|
|
|
An important consideration of the plugin system is ensuring any plugin invoked
|
|
by Vault is authentic and maintains integrity. As a result, Vault only allows
|
|
manual plugin registration from an explicitly configured **plugin directory**
|
|
and only enables plugins with a valid **catalog** entry.
|
|
|
|
The plugin directory must be accessible from the Vault server and cannot be a
|
|
symbolic link. The default Vault configuration does not include a plugin
|
|
directory and you cannot register plugins manually until you configure a plugin
|
|
directory.
|
|
|
|
The plugin catalog lives at the Vault barrier and tracks currently registered
|
|
plugins. At registration time, Vault verifies the plugin artifact exists in the
|
|
plugin directory and matches the provided SHA256 checksum before updating the
|
|
catalog.
|
|
|
|
Registering a plugin makes the plugin visible and executable by Vault backends,
|
|
but the plugin process does not run until you enable it on a specific mount path.
|
|
|
|
@include 'tips/get-plugins.mdx'
|
|
|
|
|
|
## Plugin process execution
|
|
|
|
Before starting a plugin process, Vault looks up the plugin by name in the
|
|
plugin catalog and checks the SHA256 of the plugin artifact against the registered
|
|
SHA256 sum. If the sums match, Vault starts the plugin using the command
|
|
registered in the catalog along with a JWT formatted response wrapping token and
|
|
any relevant [mlock](/vault/docs/configuration#disable_mlock) settings.
|
|
|
|
Vault spawns built-in plugins within the Vault process and external plugins as
|
|
separate processes, with Vault as the parent process.
|
|
|
|
Active Vault nodes and performance standby nodes can both spawn external plugin
|
|
processes. Plugin processes continue to run after spawning until Vault
|
|
explicitly terminates them. Common termination events are:
|
|
|
|
- Vault active node step-down
|
|
- Vault barrier seal
|
|
- Vault graceful shutdown
|
|
- Disabling a secrets engine or authN method that uses external plugins
|
|
- Database configured connection deletion
|
|
- Database configured connection update
|
|
- Database configured connection reset request
|
|
- Database root credentials rotation
|
|
- WAL rollback from a previously failed root credentials rotation operation
|
|
|
|
Vault manages the plugin process lifecycle automatically. The process starts
|
|
when you enable a plugin, but Vault starts and terminates the plugin processes
|
|
as needed through other internal processes. Since Vault manages and tracks the
|
|
lifecycle of its plugins, we do not recommend terminating plugins manually.
|
|
If Vault terminates a plugin process out-of-band, Vault lazily reloads the
|
|
process when it receives a client request that requires the plugin.
|
|
|
|
### Multiplexing
|
|
|
|
Vault allows plugin multiplexing to avoid spawning multiple processes for mounts
|
|
of the same type. When Vault runs plugins that implement multiplexing, it uses a
|
|
single plugin process for all mounts of that type across all Vault namespaces.
|
|
Multiplexing a plugin does not affect the current behavior of existing
|
|
plugins.
|
|
|
|
More resources on implementing plugin multiplexing:
|
|
|
|
- [Database secrets engines](/vault/docs/secrets/databases/custom#serving-a-plugin-with-multiplexing)
|
|
- [Secrets engines and auth methods](/vault/docs/plugins/plugin-development)
|
|
|
|
|
|
## Plugin communication
|
|
|
|
Vault communicates securely with plugins through a mutually authenticated
|
|
TLS connection to the RPC server on the plugin side. HashiCorp-managed plugins
|
|
use the AutoMTLS feature of [go-plugin](https://www.github.com/hashicorp/go-plugin)
|
|
to automatically negotiate mutual TLS for transport authentication.
|
|
|
|
Built-in plugins included with the Vault binary at compile time already
|
|
know the correct API address to establish a TLS connection, but you must set the
|
|
[`api_addr`](/vault/docs/configuration#api_addr) parameter in your Vault
|
|
configuration so manually registered plugins can establish communication with
|
|
the Vault server at mount time. If the storage backend has HA enabled and
|
|
supports automatic host address detection (e.g. Consul), Vault tries to
|
|
determine the `api_addr` automatically.
|
|
|
|
|
|
## Performance scaling
|
|
|
|
Plugins running in Vault Enterprise can leverage
|
|
[performance standbys](/vault/docs/enterprise/performance-standby) without
|
|
explicit action by the plugin author. By default, Vault Enterprise tries to
|
|
handle all requests, including requests to plugins, on performance standbys.
|
|
|
|
If the plugin request tries to write to storage, the request receives a
|
|
read-only error, and Vault transparently re-routes the full, original request to
|
|
the active node. As a result, plugins can scale horizontally on Vault Enterprise
|
|
without explicit code changes to the plugin.
|