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.

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 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
• Secrets engines and auth methods

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