Plugin system

Vault is a plugin host. Auth methods, secret engines, and database plugins all use the same gRPC plugin protocol; they're either compiled in (built-ins) or run as separate binaries that Vault execs and talks to over gRPC. Source: sdk/plugin/, vault/plugincatalog/, helper/builtinplugins/.

Purpose

• Extend Vault without recompiling the binary.
• Sandbox plugin code in a separate process so a plugin crash doesn't take down Vault.
• Support reloading and version pinning operationally.

Three flavors

Kind	Where they live	Examples
Built-in (compiled in)	builtin/credential/, builtin/logical/ (in this repo) and the vault-plugin-* modules imported by helper/builtinplugins/registry_full.go	userpass, kv, pki, transit, aws, kubernetes
Database plugins (compiled in)	plugins/database/ and external vault-plugin-database-* modules	mysql, postgresql, mongodb, redis
External plugins	Any binary the operator registers	Custom auth, custom secret engines, anything not in the helper/builtinplugins registry

Every flavor talks to Vault through sdk/logical.Backend. The only difference is how the backend gets started: built-ins call a Factory directly; external plugins are exec'd by the catalog.

Lifecycle of an external plugin

sequenceDiagram
    participant Op as Operator
    participant CLI as vault plugin register
    participant C as PluginCatalog
    participant FS as Plugin dir
    participant M as Mount

    Op->>FS: drop binary in plugin_directory
    Op->>CLI: vault plugin register -sha256=<hex> -version=v0.1 my-plugin
    CLI->>C: persist runner record
    Op->>M: vault secrets enable -plugin-name=my-plugin -path=foo plugin
    M->>C: lookup runner
    M->>FS: exec binary, gRPC handshake
    FS-->>M: backend ready

The exec'd plugin's main() calls plugin.ServeMultiplex(...), which sets up a gRPC server on a Unix socket and writes a one-line magic cookie to stdout. Vault reads the cookie, opens the socket, and starts issuing logical.Requests.

Versioning

vault plugin register -version=... records a version in the catalog. vault secrets enable -plugin-version=... pins a mount to that version. Operators can keep multiple versions registered simultaneously and roll mounts forward independently.

MountConfig.OverridePinnedVersion is the safety override for emergency re-pinning.

Plugin runtimes

vault plugin runtime register configures alternative runtimes: native exec or container-backed (containerd, runc). Each plugin can be bound to a runtime by name. This lets operators run plugins in OCI containers with dropped privileges — without changing the plugin code.

Reload semantics

vault plugin reload -plugin <name> rolls every mount of that plugin: existing connections are drained, the plugin process is killed, a fresh one is spawned, and traffic resumes. This is how operators ship security patches to plugins without restarting Vault itself.

vault plugin reload-status -plugin <name> reports the rolling state across cluster members.

Multiplexing (database plugins)

Database plugins use the v5 multiplexed protocol (sdk/plugin/plugin_v5.go). One process handles many roles, so a single MySQL plugin can manage hundreds of role configurations on the same database/ mount. Without multiplexing, each role would be its own subprocess.

Built-in registry

helper/builtinplugins/registry.go defines the minimal set always compiled in (userpass, cert, approle, jwt, oidc, kv, pki, ssh, transit). registry_full.go extends it with everything in the full edition. Building with -tags=minimal selects the minimal set, which makes for a smaller binary suitable for embedded use cases.

The registry also marks deprecated and removed plugins (e.g. the original app-id) so attempting to mount one fails with a clear error.

Integration points

• Auth methods: see Auth methods.
• Secret engines: see Secret engines.
• Plugin catalog: see Plugin catalog.
• SDK: see packages/sdk.

Entry points for modification

• Author a plugin: import sdk/plugin from your main() and sdk/framework for paths.
• Add a built-in: drop into builtin/credential/ or builtin/logical/, register in helper/builtinplugins/registry*.go.
• New runtime kind: extend vault/plugincatalog/plugin_runtime_catalog.go.
• Bump the protocol version: sdk/plugin/plugin_v5.go is the multiplexed protocol; the older plugin.go serves as a v4 compatibility layer.