mirror of
https://github.com/hashicorp/vault.git
synced 2025-08-16 19:47:02 +02:00
106 lines
3.9 KiB
Plaintext
106 lines
3.9 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: Containerized plugins
|
|
description: External Vault plugins can be run in containers.
|
|
---
|
|
|
|
# Containerized plugins
|
|
|
|
@include 'alerts/beta.mdx'
|
|
|
|
<Note title="Limited OS support">
|
|
|
|
Support for the `container` runtime is currently limited to Linux.
|
|
|
|
</Note>
|
|
|
|
By default, external plugins run as subprocesses that share Vault's user and
|
|
environment variables. Administrators managing Vault instances on Linux can
|
|
choose to run external plugins in containers. Running plugins in containers
|
|
increases the isolation between plugins, and between 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.5.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:
|
|
|
|
- Docker and Podman.
|
|
- Default and rootless container engine.
|
|
- OCI runtimes runsc and runc.
|
|
- Plugin container images with 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.
|
|
|
|
### Rootless installation with non-root container user
|
|
|
|
Not currently supported. We are hoping to provide support in future.
|
|
|
|
### runsc runtime
|
|
|
|
- You must pass an additional `--host-uds=all` flag to the `runsc` runtime.
|
|
|
|
### Rootless installation with `runsc`
|
|
|
|
- Does not currently support cgroup limits.
|
|
- You must pass an additional `--ignore-cgroups` flag to the `runsc` runtime.
|
|
|
|
### Non-root container user with mlock enabled
|
|
|
|
- You must set the IPC_LOCK capability on the plugin binary.
|
|
|
|
### Rootless container engine with mlock enabled
|
|
|
|
- You must set the IPC_LOCK capability on the container engine's binary.
|
|
- You do not need to set the IPC_LOCK capability if running with Docker and runsc.
|
|
The `runsc` runtime supports mlock syscalls in rootless Docker without needing
|
|
IPC_LOCK itself.
|
|
|
|
## 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.
|