Docker plugin for Hashicorp Vault

• Installation
  • As a Docker plugin (recommended)
  • As an external program
• Usage
  • Docker Volume driver
  • More examples
    • K/V v1 example
    • K/V v2 example
• References
  • Authentication Methods
    • AppRole
    • TLS certificates
    • Token
    • Username/password
  • Secrets engines
    • Common options
    • Key/Value engine
    • Database engines
    • PKI engine
• Development
  • Compilation
    • As a local binary file
    • As a docker image
    • As a docker plugin
  • Development rationals
• Notes
  • Rationals on Docker Plugin capabilities requirement
  • Docker limitation on Volume options inheritances

Installation

As a Docker plugin (recommended)

docker plugin install anthochamp/vaultfs-amd64 --alias vaultfs

# check current environment 
docker plugin inspect vaultfs

# change environment
docker plugin set vaultfs DPV_VAULT_URL="https://your-vault-host:8200" 

docker plugin enable vaultfs

# start creating volumes...

As an external program

• Compile the binary version of the program
• On a systemd compatible system, use packages/systemd/docker-plugin-vault.service and packages/systemd/docker-plugin-vault.socket.

Usage

Docker Volume driver

You want a volume secrets, bound to the 4th version of your credentials secret stored in a KV v2 engine mounted on app:

docker volume create \
    --driver vaultfs \
    -o auth-method=token
    -o token=<token>
    -o engine-mount=app
    -o engine-type=kv
    -o kv-engine-version=2
    -o secret=credentials
    -o kv-secret-version=4
    secrets

docker run -it --volume secrets:/run/secrets alpine sh

Given that the 4th version of your credentials secrets has two keys username and password, you'll find two files /run/mysecret/username and /run/mysecret/password containg the raw values of the associated Vault Secret keys.

Provided you didn't customized the default values from the command-line or the Docker plugin environment, the above command can be simplified as:

docker volume create \
    --driver vaultfs \
    -o token=<token>
    -o engine-mount=app
    credentials@4

docker run -it --volume credentials@4:/run/secrets alpine sh

More examples

Minimal example for generating a lease for credentials for the role public in the database engine:

docker volume create \
    --driver vaultfs \
    -o secret=public
    mycredentials

The plugin will automatically renew the lease or request a new lease if renewing is refused.

K/V v1 example

Example for the secret credentials in the app:

docker volume create \
    --driver vaultfs \
    -o engine-type=kv
    -o engine=kv
    -o kv-engine-version=1
    -o secret=credentials
    mycredentials

Alternative example if the Docker Volume name is the same as the Vault Secret path:

docker volume create \
    --driver vaultfs \
    -o engine-type=kv
    -o engine=app
    -o kv-engine-version=1
    credentials

K/V v2 example

Example for the 4th version of the secret credentials in the secret app:

docker volume create \
    --driver vaultfs \
    -o engine-type=kv
    -o engine=app
    -o kv-engine-version=2
    -o secret=credentials
    -o kv-secret-version=4
    mycredentials

Alternative example if the Docker Volume name is the same as the Vault Secret path:

docker volume create \
    --driver vaultfs \
    -o engine-type=kv
    -o engine=app
    -o kv-engine-version=2
    credentials@4

References

Notes: The default values of each fields can be changed using Docker plugin options.

Authentication Methods

The following Vault authentication methods are supported:

auth-method	Documentation	Default auth-mount value
approle	AppRole	approle
cert	SSL/TLS certificates	cert
token	Token	token
userpass	Username / Password	userpass

All the authentication methods supports the following Docker Volume options:

Volume option	Default value	Description
auth-method	token	Vault auth method id (case-insensitive)
auth-mount	Based on auth-method, see table above	Path to the Vault auth method
auth-token-renew-ttl	0	The authentication token TTL (in seconds) to request to the engine.

AppRole

Vault AppRole authentication method, selectable via auth-method=approle, supports the following additional Docker Volume options:

Volume option	Default value	Description
auth-role-id	none	The RoleID to use for authentication
auth-role-id-file	none	The path to a file containing the RoleID to use for authentication
auth-secret-id	none	The SecretID to use for authentication
auth-secret-id-file	none	The path to a file containing the SecretID to use for authentication

cf. https://developer.hashicorp.com/vault/docs/auth/approle#code-example

Example:

docker volume create \
    --driver vaultfs \
    -o secret=credentials
    -o auth-method=approle
    -o auth-role-id=<role-id>
    -o auth-secret-id=<secret-id>
    mycredentials

TLS certificates

Vault TLS certificates authentication method, selectable via auth-method=cert, supports the following additional Docker Volume options:

Volume option	Default value	Description
auth-cert-file	none	The path to the client certificate to use for authentication
auth-cert-key-file	none	The path to the client certificate's key to use for authentication

Example:

docker volume create \
    --driver vaultfs \
    -o secret=credentials
    -o auth-method=cert
    -o cert-file=/path/to/volume/cert.pem
    -o cert-key-file=/path/to/volume/key.pem
    mycredentials

Token

Vault Token authentication method, selectable via auth-method=token, supports the following additional Docker Volume options:

Volume option	Default value	Description
auth-token	none	The token to use for authentication
auth-token-file	none	The path to a file containing the token to use for authentication

Example:

docker volume create \
    --driver vaultfs \
    -o secret=credentials
    -o auth-method=token
    -o auth-token=<token>
    mycredentials

Username/password

Vault Userpass authentication method, selectable via auth-method=userpass, supports the following additional Docker Volume options:

Volume option	Default value	Description
username	none	The username to use for authentication
username-file	none	The path to a file containing the username to use for authentication
password	none	The password to use for authentication
password-file	none	The path to a file containing the password to use for authentication

Example:

docker volume create \
    --driver vaultfs \
    -o secret=credentials
    -o auth-method=userpass
    -o username=<username>
    -o password=<password>
    mycredentials

Secrets engines

The following Vault Secrets engines¹ are supported:

Engine	engine-type	Default engine-mount value
Key/Value	kv	secret
Database	db	database
PKI	pki	pki

Common options

All the above secrets engines support the following Docker Volume options:

Volume option	Default value	Description
engine-type	kv	Vault engine internal type identifier (case-insensitive)
engine-mount	Based on engine-type, see table above	Mount path to the Vault engine (Vault's CLI -mount equivalent)
secret	none	Path to the secret inside the Vault engine
token-renew-ttl	0	The secret token TTL (in seconds) to request to the engine
mount-uid	0	User ID of the secret directory and its fields files
mount-gid	0	Group ID of the secret directory and its fields files
mount-mode	0550	Access mode of the secret directory
field-mount-mode	0440	Access mode of the secret's fields files

Key/Value engine

Vault Key/Value engine² supports the following additional Docker Volume options:

Volume option	Default value	Description
kv-engine-version	1	K/V engine version (1 or 2)
kv-secret-version	none	The version of the secret as an integer or latest. No value defined is the same as latest. Relevant only if kv-engine-version=2.

Database engines

Vault Database engines³ support the following additional Docker Volume options:

Volume option	Default value	Description
db-role	none	Path to the database role

PKI engine

Vault PKI engine⁴ supports the following additional Docker Volume options:

Volume option	Default value	Description

Development

Compilation

Clone the repository.

As a local binary file

Install golang using the official documentation: https://go.dev/doc/install.

Build the plugin :

./scripts/build.sh

./src/docker-plugin-vaultfs --help

As a docker image

./scripts/docker-image/build.sh linux/amd64 vaultfs:latest

docker run -it --cap-add=IPC_LOCK --cap-add=SYS_ADMIN --device /dev/fuse --security-opt apparmor:unconfined vaultfs:latest

As a docker plugin

# requires sudo access
./scripts/docker-plugin/create.sh linux/amd64 vaultfs

docker plugin enable vaultfs

Development rationals

• Q: Why not use docker/go-plugins-helpers ? A: docker/go-plugins-helpers#123

Notes

Rationals on Docker Plugin capabilities requirement

• CAP_SYS_ADMIN is required to mount/unmount the FUSE volume FS used for the Docker Volume driver;
• CAP_IPC_LOCK is required to lock the memory so that Vault secrets stays in memory and do not get leaked on swap.

Reference: https://man7.org/linux/man-pages/man7/capabilities.7.html

Docker limitation on Volume options inheritances

docker plugin set vaultfs auth-method=token token=<tokenA>

docker volume create \
    --driver vaultfs \
    -o token=<tokenB>
    mysecret

docker run -it \
    --mount volume-driver=vaultfs,source=mysecret,target=/run/mysecret,volume-opt=token=<tokenC> \
    alpine sh

In the example above, all the volume options (volume-opt) used in the --mount argument to run the alpine container won't be registered by the plugin.

This is a limitation of the Docker plugin protocol. Docker only sends volume options if the volume hasn't been created yet.

In the above case, since the volume mysecret has already been created via the docker volume create command, any following reference to that volume will get its volume options ignored. Effectively, the alpine container will use tokenB to access the Vault Secret.

Footnotes

1. Vault Secrets documentation (official) ↩

2. Vault Key/Value engine documentation (official) ↩

3. Vault Databases engines documentation (official) ↩

4. Vault PKI engine documentation (official) ↩