Containerized plugins overview
Limited OS support
Support for the container
runtime is currently limited to Linux.
Vault has a wide selection of builtin plugins to support integrating with other systems. For example, you can use plugins to exchange app identity information with an authentication service to receive a Vault token, or manage database credentials. You can also register external plugins with your Vault instance to extend the capabilities of your Vault server.
By default, external plugins run as subprocesses that share the user and environment variables of your Vault instance. Administrators managing Vault instances on Linux can choose to run external plugins in containers. Running plugins in containers increases the isolation between individual plugins and between the plugins and Vault.
System requirements
Your Vault instance must be running on Linux.
Your environment must provide Vault local access to the Docker Engine API. Vault uses the Docker SDK to manage containerized plugins.
You must have a valid container runtime installed. We recommend installing gVisor for your container runtime as Vault specifies the
runsc
runtime by default.You must have all your plugin container images pulled and available locally. Vault does not currently support pulling images as part of the plugin registration process.
Plugin requirements
All plugins have the following basic requirements to be containerized:
Your plugin must be built with at least v1.6.0 of the HashiCorp
go-plugin
library.The image entrypoint should run the plugin binary.
Some configurations have additional requirements for the container image, listed in supported configurations.
Supported configurations
Vault's containerized plugins are compatible with a variety of configurations. In particular, it has been tested with the following:
- Default and rootless Docker.
- OCI-compatible runtimes
runsc
andrunc
. - Plugin container images running as root and non-root users.
- Mlock disabled or enabled.
Not all combinations work and some have additional requirements, listed below. If you use a configuration that matches multiple headings, you should combine the requirements from each matching heading.
runsc
runtime
- You must pass an additional
--host-uds=create
flag to therunsc
runtime.
Rootless Docker with runsc
runtime
- You must pass an additional
--ignore-cgroups
flag to therunsc
runtime.- Cgroup limits are not currently supported for this configuration.
Rootless Docker with non-root container user
- You must use a container plugin runtime with
rootless
enabled. - Your filesystem must have Posix 1e ACL support, available by default in most modern Linux file systems.
- Only supported for gVisor's
runsc
runtime.
Rootless Docker with mlock enabled
- Only supported for gVisor's
runsc
runtime.
Non-root container user with mlock enabled
- You must set the
IPC_LOCK
capability on the plugin binary.
Container lifecycle and metadata
Like any other external plugin, Vault will automatically manage the lifecycle of plugin containers. If they are killed out of band, Vault will restart them before servicing any requests that need to be handled by them. Vault will also multiplex multiple mounts to be serviced by the same container if the plugin supports multiplexing.
Vault labels each plugin container with a standard set of metadata to help identify the owner of the container, including the cluster ID, Vault's own process ID, and the plugin's name, type, and version.
Plugin runtimes
Users who require more control over plugin containers can use the "plugin
runtime" APIs for finer grained settings. See the CLI documentation for
vault plugin runtime
for more details.