| 1 |
[[ch-docker-linstor]] |
| 2 |
== LINSTOR Volumes in Docker |
| 3 |
|
| 4 |
indexterm:[docker]This chapter describes LINSTOR volumes in Docker as |
| 5 |
managed by the https://github.com/LINBIT/linstor-docker-volume-go[LINSTOR |
| 6 |
Docker Volume Plugin]. |
| 7 |
|
| 8 |
[[s-docker-linstor-overview]] |
| 9 |
=== Docker Overview |
| 10 |
|
| 11 |
_Docker_ is a platform for developing, shipping, and running |
| 12 |
applications in the form of Linux containers. For stateful |
| 13 |
applications that require data persistence, Docker supports |
| 14 |
the use of persistent _volumes_ and _volume_drivers_. |
| 15 |
|
| 16 |
The https://github.com/LINBIT/linstor-docker-volume-go[LINSTOR |
| 17 |
Docker Volume Plugin] is a volume driver that provisions persistent |
| 18 |
volumes from a LINSTOR cluster for Docker containers. |
| 19 |
|
| 20 |
[[s-docker-linstor-install]] |
| 21 |
=== LINSTOR Plugin for Docker Installation |
| 22 |
|
| 23 |
To install the `linstor-docker-volume` plugin provided by LINBIT, you'll |
| 24 |
need to have a working LINSTOR cluster. After that the plugin can be installed from the public docker hub. |
| 25 |
|
| 26 |
---- |
| 27 |
# docker plugin install linbit/linstor-docker-volume --grant-all-permissions |
| 28 |
---- |
| 29 |
|
| 30 |
NOTE: The `--grant-all-permissions` flag will automatically grant all |
| 31 |
permissions needed to successfully install the plugin. If you'd like to |
| 32 |
manually accept these, omit the flag from the command above. |
| 33 |
|
| 34 |
The implicit `:latest` tag is the latest `amd64` version. We currently also build for `arm64` with the |
| 35 |
according tag. Installing the `arm64` plugin looks like this: |
| 36 |
|
| 37 |
---- |
| 38 |
# docker plugin install linbit/linstor-docker-volume:arm64 --grant-all-permissions |
| 39 |
---- |
| 40 |
|
| 41 |
[[s-docker-linstor-configuration]] |
| 42 |
=== LINSTOR Plugin for Docker Configuration |
| 43 |
|
| 44 |
As the plugin has to communicate to the LINSTOR controller via the |
| 45 |
LINSTOR python library, we must tell the plugin where to find the |
| 46 |
LINSTOR Controller node in its configuration file: |
| 47 |
|
| 48 |
---- |
| 49 |
# cat /etc/linstor/docker-volume.conf |
| 50 |
[global] |
| 51 |
controllers = linstor://hostnameofcontroller |
| 52 |
---- |
| 53 |
|
| 54 |
|
| 55 |
A more extensive example could look like this: |
| 56 |
|
| 57 |
---- |
| 58 |
# cat /etc/linstor/docker-volume.conf |
| 59 |
[global] |
| 60 |
storagepool = thin-lvm |
| 61 |
fs = ext4 |
| 62 |
fsopts = -E discard |
| 63 |
size = 100MB |
| 64 |
replicas = 2 |
| 65 |
---- |
| 66 |
|
| 67 |
=== Example Usage |
| 68 |
|
| 69 |
The following are some examples of how you might use the LINSTOR |
| 70 |
Docker Volume Plugin. |
| 71 |
In the following we expect a cluster consisting of three nodes |
| 72 |
(alpha, bravo, and charlie). |
| 73 |
|
| 74 |
|
| 75 |
==== Example 1 - typical docker pattern |
| 76 |
|
| 77 |
On node alpha: |
| 78 |
|
| 79 |
---- |
| 80 |
$ docker volume create -d linbit/linstor-docker-volume \ |
| 81 |
--opt fs=xfs --opt size=200 lsvol |
| 82 |
$ docker run -it --rm --name=cont \ |
| 83 |
-v lsvol:/data --volume-driver=linbit/linstor-docker-volume busybox sh |
| 84 |
$ root@cont: echo "foo" > /data/test.txt |
| 85 |
$ root@cont: exit |
| 86 |
---- |
| 87 |
|
| 88 |
On node bravo: |
| 89 |
|
| 90 |
---- |
| 91 |
$ docker run -it --rm --name=cont \ |
| 92 |
-v lsvol:/data --volume-driver=linbit/linstor-docker-volume busybox sh |
| 93 |
$ root@cont: cat /data/test.txt |
| 94 |
foo |
| 95 |
$ root@cont: exit |
| 96 |
$ docker volume rm lsvol |
| 97 |
---- |
| 98 |
|
| 99 |
==== Example 2 - one diskful assignment by name, two nodes diskless |
| 100 |
|
| 101 |
---- |
| 102 |
$ docker volume create -d linbit/linstor-docker-volume --opt nodes=bravo lsvol |
| 103 |
---- |
| 104 |
|
| 105 |
==== Example 3 - one diskful assignment, no matter where, two nodes diskless |
| 106 |
|
| 107 |
---- |
| 108 |
$ docker volume create -d linbit/linstor-docker-volume --opt replicas=1 lsvol |
| 109 |
---- |
| 110 |
|
| 111 |
==== Example 4 - two diskful assignments by name, charlie diskless |
| 112 |
|
| 113 |
---- |
| 114 |
$ docker volume create -d linbit/linstor-docker-volume --opt nodes=alpha,bravo lsvol |
| 115 |
---- |
| 116 |
|
| 117 |
==== Example 5 - two diskful assignments, no matter where, one node diskless |
| 118 |
|
| 119 |
---- |
| 120 |
$ docker volume create -d linbit/linstor-docker-volume --opt replicas=2 lsvol |
| 121 |
---- |
| 122 |
|
| 123 |
==== Example 6 - using LINSTOR volumes with services from Docker swarm manager node |
| 124 |
|
| 125 |
---- |
| 126 |
$ docker service create \ |
| 127 |
--mount type=volume,src=lsvol,dst=/data,volume-driver=linbit/linstor-docker-volume \ |
| 128 |
--name swarmsrvc busybox sh -c "while true; do sleep 1000s; done" |
| 129 |
---- |
| 130 |
|
| 131 |
TIP: Docker services do not accept the `-v` or `--volume` syntax, you |
| 132 |
must use the `--mount` syntax. Docker `run` will accept either syntax. |