Add a containerized secrets plugin to Vault
Beta feature
Beta functionality is stable but possibly incomplete and subject to change. We strongly discourage using beta features in production deployments of Vault
Run your external secrets plugins in containers to increases the isolation between the plugin and Vault.
Before you start
- Your Vault instance must be running on Linux.
- Your Vault instance must have local access to the Docker Engine API. Vault uses the Docker SDK to manage containerized plugins.
- You must have gVisor
installed. Vault uses
runsc
as the entrypoint to your container runtime. - If you are using a container runtime other than gVisor, you must have a
runsc
-compatible container runtime installed.
Step 1: Install your container engine
Install one of the supported container engines:
Step 2: Configure your container runtime
Update your container engine to use runsc
for Unix sockets between the host
and plugin binary.
Add
runsc
to your Docker daemon configuration:Restart Docker:
Step 3: Update the HashiCorp go-plugin
library
You must build your plugin locally with v1.5.0+ of the HashiCorp
go-plugin
library to ensure the
finished binary is compatible with containerization.
Use go install
to pull the latest version of the plugin library from the
hashicorp/go-plugin
repo on GitHub:
The Vault SDK includes go-plugin
If you build with the Vault SDK, you can update go-plugin
with go install
by pulling the latest SDK version from the hashicorp/vault
repo:
go install github.com/hashicorp/vault/sdk@latest
Step 4: Build the plugin container
Containerized plugins must run as a binary in the finished container and behave the same whether run in a container or as a standalone application:
- Build your plugin binary so it runs on Linux.
- Create a container file for your plugin with the compiled binary as the entry-point.
- Build the image with a unique tag.
For example, to build a containerized version of the built-in key-value (KV) secrets plugin for Docker:
- Clone the latest version of the KV secrets plugin from
hashicorp/vault-plugin-secrets-kv
. - Build the Go binary for Linux.
- Create an empty Dockerfile.
- Update the empty
Dockerfile
with your infrastructure build details and the compiled binary as the entry-point. - Build the container image and assign an identifiable tag.
Step 5: Register the plugin
Registering a containerized plugin with Vault is similar to registering any other external plugin that is available locally to Vault.
Store the SHA256 of the plugin image:
For example:
Register the plugin with
vault plugin register
and specify your plugin image with theoci_image
flag:For example:
Enable the new plugin for your Vault instance with
vault secrets enable
and the new plugin ID:For example:
Customize container behavior with registration flags
You can provide additional information about the image entrypoint, command,
and environment with the -command
, -args
, and -env
flags for
vault plugin register
.
Step 6: Test your plugin
Now that the container is registered with Vault, you should be able to interact with it like any other plugin. Try writing then fetching a new secret with your new plugin.
Use
vault write
to store a secret with your containerized plugin:For example:
Fetch the secret you just wrote:
For example:
Use alternative runtimes
You can force Vault to use alternative runtimes provided the runtime is installed locally.
To use an alternative runtime:
Register and name the runtime with
vault plugin runtime register
. For example, to register the default Docker runtime (runc
) asdocker-rt
:Use the
--runtime
flag during plugin registration to tell Vault what runtime to use:For example:
Troubleshooting
Invalid backend version error
If you run into the following error while registering your plugin:
it means that Vault cannot find the executable for runsc
. Confirm the
following is true before trying again:
- You have gVisor installed locally to Vault.
- The path to
runsc
is correct in you your Docker configuration. - Vault has permission to run the
runsc
executable.
If you still get errors when registering a plugin, the recommended workaround is
to use the default Docker runtime (runc
) as an
alternative runtime.