docker-btrfs-plugin - Docker Volume Driver for BTRFS volumes

docker-btrfs-plugin [ -debug ] [ -version ]

docker-btrfs-plugin is a Docker volume plugin designed to use BTRFS subvolumes as the local backend storage for each persistent named volume. It supports volume creation, removal, listing, mounting, and unmounting.

• Efficiency: Designed to be simple, fast, and have low memory requirements.
• Snapshot Management: Create, list, delete, and restore snapshots.
• Subvolume Management: Each Docker persistent named volume is bound to a nested BTRFS subvolume
• Logging & Exception Handling: Built-in mechanisms for logging and error handling.

• go: Make sure Golang build tools are installed to build the plugin.
• pandoc: Make sure pandoc is installed to create a man page from source.

• btrfs-progs: Make sure the btrfs commandline utility programs are installed for the volume plugin to operate correctly.

1. Clone the repository:

   git clone git@github.com:thailgrott/docker-btrfs-plugin.git

   Alternatively, use HTTPS:

   git clone https://github.com/thailgrott/docker-btrfs-plugin.git

2. Change into the directory:

   cd docker-btrfs-plugin

3. Enable Go modules:

   export GO111MODULE=on

4. Build the plugin:

   make

5. Install the plugin:

   sudo make install

The plugin requires a BTRFS subvolume mounted at the /var/lib/docker-btrfs-plugin directory which is where the plugin stores volumes and snapshots as BTRFS subvolumes.

1. Creating a Systemd Mount Unit Create a file named var-lib-docker-btrfs-plugin.mount under /etc/systemd/system/. You can use your preferred text editor to create and edit this file:

   sudo nano /etc/systemd/system/var-lib-docker-btrfs-plugin.mount

2. Add the Following Configuration:

   [Unit]
   Description=Mount BTRFS Subvolume for Docker BTRFS Plugin
   Documentation=man:docker-btrfs-plugin(8)
   After=local-fs.target
   
   [Mount]
   What=/btrfs_pool/volume_store
   Where=/var/lib/docker-btrfs-plugin
   Type=btrfs
   Options=subvol=/volume_store
   
   [Install]
   WantedBy=multi-user.target

3. Reload Systemd Configuration: After creating the mount unit file, reload the systemd configuration to recognize the new unit:

   sudo systemctl daemon-reload

4. Enable and Start the Mount Unit: To ensure that the mount unit is automatically started on boot and to start it immediately, use the following commands: Enable on next boot:

   sudo systemctl enable var-lib-docker-btrfs-plugin.mount

   Immediately mount:

   sudo systemctl start var-lib-docker-btrfs-plugin.mount

5. Verify the Mount: Check the status of the mount unit to ensure it is properly mounted:

   systemctl status var-lib-docker-btrfs-plugin.mount

   You can also check the mount point directly to verify that the subvolume is mounted:

   df -h /var/lib/docker-btrfs-plugin

Start the Docker daemon before starting the docker-btrfs-plugin daemon:

sudo systemctl start docker

Once Docker is up and running, start the plugin:

sudo systemctl start docker-btrfs-plugin

The docker-btrfs-plugin daemon is on-demand socket-activated. Running the docker volume ls command will automatically start the daemon.

The docker volume create command supports the creation of BTRFS subvolumes and snapshots.

Usage:

docker volume create [OPTIONS]

Options:

-d, --driver string : Specify volume driver name (default "local")
--label list : Set metadata for a volume (default [])
--name string : Specify volume name
-o, --opt map : Set driver-specific options (default map[])

BTRFS Options:

--opt snapshot

Examples:

Create a BTRFS volume named foobar with a default subvolume:

docker volume create -d btrfs --name foobar

Create a BTRFS snapshot of the foobar volume named foobar_snapshot:

docker volume create -d btrfs --opt snapshot=foobar --name foobar_snapshot

List all Docker volumes created by all drivers:

docker volume ls

Inspect a specific volume:

docker volume inspect foobar

Example output:

[
    {
        "Driver": "btrfs",
        "Labels": {},
        "Mountpoint": "/var/lib/docker-btrfs-plugin/foobar",
        "Name": "foobar",
        "Options": {},
        "Scope": "local"
    }
]

Remove a BTRFS volume:

docker volume rm foobar

Bind mount the BTRFS volume inside a container:

docker run -it -v foobar:/home fedora /bin/bash

This will bind mount the logical volume foobar into the /home directory of the container.

Currently supported environments include Fedora, Rocky, SuSE and Ubuntu

The docker-btrfs-plugin was developed by Thailgrott.