[[ch-docker-linstor]]
== LINSTOR Volumes in Docker

indexterm:[docker]This chapter describes LINSTOR volumes in Docker as
managed by the https://github.com/LINBIT/linstor-docker-volume-go[LINSTOR
Docker Volume Plugin].

[[s-docker-linstor-overview]]
=== Docker Overview

_Docker_ is a platform for developing, shipping, and running
applications in the form of Linux containers. For stateful
applications that require data persistence, Docker supports
the use of persistent _volumes_ and _volume_drivers_.

The https://github.com/LINBIT/linstor-docker-volume-go[LINSTOR
Docker Volume Plugin] is a volume driver that provisions persistent
volumes from a LINSTOR cluster for Docker containers.

[[s-docker-linstor-install]]
=== LINSTOR Plugin for Docker Installation

To install the `linstor-docker-volume` plugin provided by LINBIT, you'll
need to have a working LINSTOR cluster. After that the plugin can be installed from the public docker hub.

----
# docker plugin install linbit/linstor-docker-volume --grant-all-permissions
----

NOTE: The `--grant-all-permissions` flag will automatically grant all
permissions needed to successfully install the plugin. If you'd like to
manually accept these, omit the flag from the command above.

The implicit `:latest` tag is the latest `amd64` version. We currently also build for `arm64` with the
according tag. Installing the `arm64` plugin looks like this:

----
# docker plugin install linbit/linstor-docker-volume:arm64 --grant-all-permissions
----

[[s-docker-linstor-configuration]]
=== LINSTOR Plugin for Docker Configuration

As the plugin has to communicate to the LINSTOR controller via the
LINSTOR python library, we must tell the plugin where to find the
LINSTOR Controller node in its configuration file:

----
# cat /etc/linstor/docker-volume.conf
[global]
controllers = linstor://hostnameofcontroller
----


A more extensive example could look like this:

----
# cat /etc/linstor/docker-volume.conf
[global]
storagepool = thin-lvm
fs = ext4
fsopts = -E discard
size = 100MB
replicas = 2
----

=== Example Usage

The following are some examples of how you might use the LINSTOR
Docker Volume Plugin.
In the following we expect a cluster consisting of three nodes
(alpha, bravo, and charlie).


==== Example 1 - typical docker pattern

On node alpha:

----
$ docker volume create -d linbit/linstor-docker-volume \
        --opt fs=xfs --opt size=200 lsvol
$ docker run -it --rm --name=cont \
        -v lsvol:/data --volume-driver=linbit/linstor-docker-volume busybox sh
$ root@cont: echo "foo" > /data/test.txt
$ root@cont: exit
----

On node bravo:

----
$ docker run -it --rm --name=cont \
        -v lsvol:/data --volume-driver=linbit/linstor-docker-volume busybox sh
$ root@cont: cat /data/test.txt
  foo
$ root@cont: exit
$ docker volume rm lsvol
----

==== Example 2 - one diskful assignment by name, two nodes diskless

----
$ docker volume create -d linbit/linstor-docker-volume --opt nodes=bravo lsvol
----

==== Example 3 - one diskful assignment, no matter where, two nodes diskless

----
$ docker volume create -d linbit/linstor-docker-volume --opt replicas=1 lsvol
----

==== Example 4 - two diskful assignments by name, charlie diskless

----
$ docker volume create -d linbit/linstor-docker-volume --opt nodes=alpha,bravo lsvol
----

==== Example 5 - two diskful assignments, no matter where, one node diskless

----
$ docker volume create -d linbit/linstor-docker-volume --opt replicas=2 lsvol
----

==== Example 6 - using LINSTOR volumes with services from Docker swarm manager node

----
$ docker service create \
        --mount type=volume,src=lsvol,dst=/data,volume-driver=linbit/linstor-docker-volume \
        --name swarmsrvc busybox sh -c "while true; do sleep 1000s; done"
----

TIP: Docker services do not accept the `-v` or `--volume` syntax, you
must use the `--mount` syntax. Docker `run` will accept either syntax.
