mirror of
https://github.com/hashicorp/vault.git
synced 2025-08-10 08:37:00 +02:00
111 lines
4.3 KiB
Plaintext
111 lines
4.3 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: Containerized plugins overview
|
|
description: Learn about running external Vault plugins in containers.
|
|
---
|
|
|
|
# Containerized plugins overview
|
|
|
|
<Note title="Limited OS support">
|
|
|
|
Support for the `container` runtime is currently limited to Linux.
|
|
|
|
</Note>
|
|
|
|
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](https://pkg.go.dev/github.com/docker/docker) to
|
|
manage containerized plugins.
|
|
|
|
- **You must have a valid container runtime installed**. We recommend
|
|
[installing gVisor](https://gvisor.dev/docs/user_guide/install/) 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`](https://github.com/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).
|
|
|
|
## 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](https://docs.docker.com/engine/security/rootless/) Docker.
|
|
- OCI-compatible runtimes `runsc` and `runc`.
|
|
- Plugin container images running as root and non-root users.
|
|
- [Mlock](/vault/docs/configuration#disable_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 the `runsc` runtime.
|
|
|
|
### Rootless Docker with `runsc` runtime
|
|
|
|
- You must pass an additional `--ignore-cgroups` flag to the `runsc` 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`](/vault/docs/commands/plugin/runtime/register#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](/vault/docs/plugins/plugin-architecture#plugin-multiplexing) 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`](/vault/docs/commands/plugin/runtime) for more details.
|