Plugin catalog

The plugin catalog tracks every external plugin that's been registered with Vault: name, type, version, command, SHA-256, runtime, environment. It's the source of truth for vault plugin {register|info|list|deregister|reload}. Source: vault/plugincatalog/ and sdk/plugin/.

Purpose

• Persist plugin metadata so a restart doesn't lose registrations.
• Validate plugin binaries by checksum at mount time.
• Manage plugin runtimes (Linux containers, plain processes) so an operator can swap the runtime without reregistering each plugin.

Directory layout

vault/
├── plugin_reload.go                   # Reload-by-name and rolling-reload
└── plugincatalog/
    ├── plugin_catalog.go              # CRUD + factory for built-ins and externals
    ├── plugin_catalog_metrics.go
    ├── plugin_runtime_catalog.go      # Plugin runtimes (containerd, native)
    └── ...
sdk/plugin/                            # The plugin protocol
├── backend.go, plugin.go, plugin_v5.go
├── grpc_backend_*.go, grpc_storage.go
├── grpc_system.go
└── pb/                                # protobuf service definitions
helper/builtinplugins/                 # Registry of *built-in* plugins (compiled in)

Key abstractions

Symbol	File	Description
PluginCatalog	vault/plugincatalog/plugin_catalog.go	The catalog instance. Owns the BuiltinRegistry plus persisted external plugins.
PluginCatalog.Get	same	Returns a runner for a given (name, type, version).
PluginCatalog.Set / Delete	same	Register / deregister an external plugin.
PluginRunner	same	Resolves a plugin to a binary path or container image; computes SHA-256.
PluginRuntimeCatalog	plugin_runtime_catalog.go	A second catalog of runtimes — different ways of executing plugins.
BuiltinRegistry	helper/builtinplugins/registry.go	Compile-time registry consulted as a fallback.
sdk/plugin.NewBackend / Serve	sdk/plugin/serve.go	API used by plugin authors to expose a logical.Backend over gRPC.

Lifecycle of an external plugin

sequenceDiagram
    participant Op as Operator
    participant C as PluginCatalog
    participant FS as Filesystem
    participant Mount as MountTable
    participant P as Plugin process
    Op->>C: vault plugin register -sha256=… -version=v0.1 my-plugin
    C->>FS: stat $plugin_dir/my-plugin
    C->>FS: hash -> compare to provided SHA
    C->>FS: persist runner record under core/plugin-catalog/
    Op->>Mount: vault secrets enable -plugin-name=my-plugin -path=foo plugin
    Mount->>C: Get("my-plugin", PluginTypeSecrets, "v0.1")
    C->>P: exec plugin (gRPC handshake)
    P-->>Mount: backend ready
    Mount-->>Op: 204

Once running, the plugin is a child process whose lifecycle is tied to the mount: unmount disconnects, vault plugin reload SIGTERMs and respawns.

Versioning and pinning

• Each plugin can be registered at multiple versions; mounts pin a specific version (MountConfig.PluginVersion).
• override_pinned_version lets operators force an emergency override.
• Built-in plugins always have version v0.0.0 (their compiled-in version) unless explicitly registered.

Plugin runtimes

vault plugin runtime register and friends manage runtime profiles like containerd-backed sandboxes. The runtime tells Vault how to actually exec the plugin: native, or via a container with a configured root, env, and resource limits. The catalog binds plugins to runtimes by name so swapping a runtime doesn't require reregistering plugins.

Reload flows

plugin_reload.go implements:

• Reload by plugin name (rolls every mount of that plugin).
• Reload by mount path (drops only that mount's plugin).
• Scoped reload across cluster nodes (gossiped via the cluster channel).

Integration points

• Mount table looks up plugins through the catalog.
• command/plugin*.go provides the CLI surface.
• sdk/plugin/grpc_*.go are the gRPC bindings; plugins linked against sdk/plugin/ Serve themselves over the same protocol Vault speaks.
• Database plugins use a v5 multiplexed protocol (plugin_v5.go), letting one plugin process service many roles.

Entry points for modification

• Add a new plugin metadata field: extend the PluginRunner and bump the persisted version. Migrations live in plugincatalog/.
• Add a runtime kind: plugin_runtime_catalog.go plus the matching Run implementation.
• Customize built-in registration: helper/builtinplugins/registry.go for the minimal set, registry_full.go for the full edition.