Make sure etsts work regardless of how plugin is run

Author: ashald

Dockerfile

@@ -9,6 +9,6 @@ RUN make build && \
 
 # package
 FROM alpine
-RUN apk --no-cache add e2fsprogs xfsprogs
+RUN apk --no-cache add e2fsprogs xfsprogs util-linux && rm -rf /usr/share/terminfo && rm -rf /etc/terminfo
 COPY --from=builder /docker-volume-loopback /
 CMD [ "/docker-volume-loopback" ]

README.md

@@ -1,9 +1,6 @@
-# Performance
-https://serverfault.com/questions/166748/performance-of-loopback-filesystems
-https://kernelnewbies.org/Linux_4.4#Faster_and_leaner_loop_device_with_Direct_I.2FO_and_Asynchronous_I.2FO_support
-
-https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=bc07c10a3603a5ab3ef01ba42b3d41f9ac63d1b6
+# Docker Volume Loopback
 
+## Overview
 
 ### Sparse
 
@@ -12,17 +9,85 @@ https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=bc
 |xfs  | 0%/1%         | 100%/100%  |
 |ext4 | 0%/3%         | 100%/3%    |
 
+## Installation
+
+### Automatic
+
+### Manual
+
+## Usage
+
+## Known Issues and Limitations
+
+### Compatibility
+
+When dealing with volumes based on `XFS` filesystem the driver depends on `mkfs.xfs` from `xfsprogs` package.
+Starting from `v3.2.3` (released on 2015-06-10) of the package newly created `XfS` filesystems default to use of a newer
+metadata format that is only supported by Linux kernel `v3.16` and above.
+
+This manifests as a failure during an attempt to mount a volume - the filesystem will be initialized properly upon
+volume creation but kernel will not be able to mount it.  
+
+This is unlikely to be an issue if _manual_ installation mode is used as the version of `xfsprogs` available via Linux
+distribution-specific package manager is likely to be compatible with the version of Linux kernel required.
+When _automatic_ installation is used though the plugin is \[effectively\] distributed as a container image based on
+Alpine Linux which \[at the moment of writing\] uses at least `v4.19.0` of `xfsprogs` package. This means that in case
+the plugin will be installed on a system based on older version of kernel it won't be able to use `XFS` filesystem.
+
+There is a workaround available that can be used to circumvent the issue: use an extra `-m crc=0` parameter when calling
+`mkfs.xfs` which will force use of older version of metadata compatible with older versions of kernel. Unfortunately this
+cannot be a default behavior as this flag was added only to `xfsprogs` starting from `v3.2.0` and therefore is unlikely
+to be available on similar systems based on outdated versions of kernel \[in case _manual_ installation mode is used\].
+
+ 
+While the workaround is trivial in essence it is trickier to implement as would require fir amount of code to run
+dynamic checks for versions of kernel and `mkfs.xfs`. Hence a conscious decision to not implement this behavior initially.
+In case there will be interest if support for older systems it can be easily added and should be requested via a GitHub
+issue.
+
+Below is the list of distributions known to be affected by this:
+
+| Distribution | Version               | Release Date | End of Life Date |
+| ------------ | --------------------- | ------------ | ---------------- |
+| Ubuntu       | 14.04 LTS Trusty Tahr | 2014-04-17   | 2019-04-01       | 
+
+
+Entries are going to be removed from the table upon reaching EOL.
+May the list above be exhausted this notice will be dropped altogether.
+
+### Performance
+
+[Loop devices are notorious for their "bad" performance]. While it's not arguable that they incur and some overhead both
+in terms of CPU and memory it, it always should be evaluated in a context of a concrete use case. Generally speaking,
+if one does not constantly `fsync` after each write to a filesystem based on a loopback device \[and just let kernel do its job\]
+the performance seems to be comparable to regular block devices. Although, it must be noted that in such cases write
+operations are susceptible to the "double caching" issue where data are cached first while being written to the loopback
+device backed filesystem and then data cached again while changes are bing finally committed to the backing block device.
+This means that there may be a delay (on average, up to a 2 x 30 seconds = 1 minute) before writes will become durable
+by being committed to the backing block device. Also, cache buffers are usually freed and committed more often when
+system runs low on memory which means that usage of loopback devices is unlikely to degrade performance of the system as
+a whole but system running low on memory is likely to have loopback devices performing worse. For the record, cache memory
+is not being counted against `memory.max_usage_in_bytes` cgroup controller and therefore is ignored by Docker.
+
+Last but not least, the release of Linux kernel `v4.4` includes "[Faster and leaner loop device with Direct I/O and Asynchronous I/O support]"
+which [circumvents the "double buffering" issue].
+
+In terms of CPU, while no comprehensive benchmarks have been done during development of the plugin, the overhead seem to
+be negligible.
+
 
 ## Development
-Go 1.11
+Go 1.11 modules
+
 ```bash
 go mod vendor
 go mod tidy
 ```
 
-# Extra
-validate options
+## License
+
+This is free and unencumbered software released into the public domain. See [LICENSE](./LICENSE)
 
-if _, err := exec.LookPath("mkfs.xfs"); err != nil {
-		logrus.Fatal("mkfs.xfs is not available, please install xfsprogs to continue")
-	}
+[Loop devices are notorious for their "bad" performance]: https://serverfault.com/questions/166748/performance-of-loopback-filesystems
+[Faster and leaner loop device with Direct I/O and Asynchronous I/O support]: https://kernelnewbies.org/Linux_4.4#Faster_and_leaner_loop_device_with_Direct_I.2FO_and_Asynchronous_I.2FO_support
+[circumvents the "double buffering" issue]: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=bc07c10a3603a5ab3ef01ba42b3d41f9ac63d1b6

Vagrantfile

@@ -1,5 +1,5 @@
 Vagrant.configure(2) do |config|
-  config.vm.box = "ubuntu/trusty64"
+  config.vm.box = "ubuntu/bionic64"
   config.vm.provision :docker
-  config.vm.provision "shell", inline: "apt-get update && apt-get install -y jq xfsprogs"
+  config.vm.provision "shell", inline: "apt-get update && apt-get install -y binutils jq xfsprogs"
 end

manager/manager.go

@@ -18,7 +18,7 @@ var (
 
 	MkFsOptions = map[string][]string{
 		"ext4": {"-F"},
-		"xfs":  {},
+		"xfs":  {"-f"},
 	}
 
 	MountOptions = map[string][]string{

plugin/config.json

@@ -33,11 +33,11 @@
             "Description": "Path to the plugin UNIX socket",
             "Name": "SOCKET",
             "Settable": [],
-            "Value": "/run/docker/plugins/docker-volume-loop.sock"
+            "Value": "/run/docker/plugins/loop.sock"
         }
     ],
     "Interface": {
-        "Socket": "docker-volume-loop.sock",
+        "Socket": "loop.sock",
         "Types": ["docker.volumedriver/1.0"]
     },
     "Linux": {
@@ -61,7 +61,7 @@
         },
         {
             "Destination": "/srv",
-            "Options": ["bind"],
+            "Options": ["rbind"],
             "Source": "/",
             "Type": "bind"
         }

tests/test.sh

@@ -4,25 +4,30 @@
 
 IMAGE="alpine"
 DRIVER="docker-volume-loopback"
-DATA_DIR="/var/lib/${DRIVER}"
+eval $(strings -a /proc/$(pidof docker-volume-loopback)/environ | grep DATA_DIR)
+DATA_DIR=${DATA_DIR:-"/var/lib/${DRIVER}"} # a default fall-back
+
+run() {
+    nsenter -t $(pidof "${DRIVER}") -a "${@}"
+}
 
 oneTimeSetUp() {
     docker volume rm $(docker volume create -d "${DRIVER}" -o size=100MiB) &> /dev/null
 }
 
 setUp() {
     HANDLE=$(mktemp -u)
-    truncate -s "${BASE_SIZE:-2G}" "${HANDLE}"
+    run truncate -s "${BASE_SIZE:-2G}" "${HANDLE}"
 
 
     case "${BASE_FS:-xfs}" in
     xfs)
-        mkfs.xfs "${HANDLE}" &> /dev/null
-        mount -o nouuid "${HANDLE}" "${DATA_DIR}"
+        run mkfs.xfs -f "${HANDLE}" &> /dev/null
+        run mount -o nouuid "${HANDLE}" "${DATA_DIR}"
         ;;
     ext*)
-        mkfs.${BASE_FS} -F "${HANDLE}" &> /dev/null
-        mount "${HANDLE}" "${DATA_DIR}"
+        run mkfs.${BASE_FS} -F "${HANDLE}" &> /dev/null
+        run mount "${HANDLE}" "${DATA_DIR}"
         ;;
     *)
         echo "Unsupported BASE fs"
@@ -32,8 +37,8 @@ setUp() {
 }
 
 tearDown() {
-    umount -ld "${DATA_DIR}"
-    rm -f "${HANDLE}"
+    run umount -ld "${DATA_DIR}"
+    run rm -f "${HANDLE}"
 }
 
 . ./shunit2

tests/test_fs_ext4.sh

@@ -11,7 +11,7 @@ testRegularVolumeChecksDiskSpaceBeforeFormatting() {
     result=$?
 
     ## because we shadow real data dir with our test volume we're sure there shouldn't be any volumes
-    count=$(ls -1 "/var/lib/${DRIVER}/" | wc -l)
+    count=$(run ls -1 "${DATA_DIR}/" | wc -l)
 
     # checks
     assertEquals "1" "${result}"
@@ -23,9 +23,8 @@ testRegularVolumeDoesNotReserveDiskSpace() {
     # setup
     volume=$(docker volume create -d "${DRIVER}" -o fs=${FS} -o sparse=false)
 
-    info=$(ls --block-size=M -ls "/var/lib/${DRIVER}/${volume}.${FS}")
-    allocated_size=$(echo ${info} | awk '{print $1}' | tr -dc '0-9')
-    apparent_size=$(echo ${info} | awk '{print $6}' | tr -dc '0-9')
+    allocated_size="$(($(run stat -c '%b %B' ${DATA_DIR}/${volume}.${FS} | tr ' ' '*')))" # allocated space in bytes
+    apparent_size="$(run stat -c '%s' ${DATA_DIR}/${volume}.${FS})"                       # apparent  space in bytes
 
     # checks
     assertTrue "Regular ${FS} volume of ${apparent_size} MiB should take less space: ${allocated_size} MiB" "[ ${allocated_size} -lt ${apparent_size} ]"
@@ -42,12 +41,11 @@ testSparseVolumeDoesNotCheckAvailableDiskSpace() {
     volume=$(docker volume create -d "${DRIVER}" -o fs=${FS} -o sparse=true -o size=10GiB)
     result=$?
 
-    info=$(ls --block-size=M -ls "/var/lib/${DRIVER}/${volume}.${FS}")
-    apparent_size=$(echo ${info} | awk '{print $6}' | tr -dc '0-9')
+    apparent_size="$(run stat -c '%s' ${DATA_DIR}/${volume}.${FS})"     # apparent  space in bytes
 
     # checks
     assertEquals "0" "${result}"
-    assertEquals "10240" "${apparent_size}"
+    assertEquals "$((10*1024*1024*1024))" "${apparent_size}"
 
     # cleanup
     docker volume rm "${volume}" > /dev/null
@@ -58,9 +56,8 @@ testSparseVolumeDoesNotReserveDiskSpace() {
     # setup
     volume=$(docker volume create -d "${DRIVER}" -o fs=${FS} -o sparse=true)
 
-    info=$(ls --block-size=M -ls "/var/lib/${DRIVER}/${volume}.${FS}")
-    allocated_size=$(echo ${info} | awk '{print $1}' | tr -dc '0-9')
-    apparent_size=$(echo ${info} | awk '{print $6}' | tr -dc '0-9')
+    allocated_size="$(($(run stat -c '%b %B' ${DATA_DIR}/${volume}.${FS} | tr ' ' '*')))" # allocated space in bytes
+    apparent_size="$(run stat -c '%s' ${DATA_DIR}/${volume}.${FS})"                       # apparent  space in bytes
 
     # checks
     assertTrue "Sparse ${FS} volume of ${apparent_size} MiB should take less space: ${allocated_size} MiB" "[ ${allocated_size} -lt ${apparent_size} ]"

tests/test_fs_xfs.sh

@@ -11,7 +11,7 @@ testRegularVolumeChecksDiskSpaceBeforeFormatting() {
     result=$?
 
     ## because we shadow real data dir with our test volume we're sure there shouldn't be any volumes
-    count=$(ls -1 "/var/lib/${DRIVER}/" | wc -l)
+    count=$(run ls -1 "${DATA_DIR}/" | wc -l)
 
     # checks
     assertEquals "1" "${result}"
@@ -22,9 +22,9 @@ testRegularVolumeReservesDiskSpace() {
     local volume info allocated_size apparent_size
     # setup
     local volume=$(docker volume create -d "${DRIVER}" -o fs=${FS} -o sparse=false)
-    local info=$(ls --block-size=M -ls "/var/lib/${DRIVER}/${volume}.${FS}")
-    local allocated_size=$(echo ${info} | awk '{print $1}' | tr -dc '0-9')
-    local apparent_size=$(echo ${info} | awk '{print $6}' | tr -dc '0-9')
+
+    allocated_size="$(($(run stat -c '%b %B' ${DATA_DIR}/${volume}.${FS} | tr ' ' '*')))" # allocated space in bytes
+    apparent_size="$(run stat -c '%s' ${DATA_DIR}/${volume}.${FS})"                       # apparent  space in bytes
 
     # checks
     assertTrue "Regular ${FS} volume of ${apparent_size} MiB should take at least same space: ${allocated_size} MiB" "[ ${allocated_size} -ge ${apparent_size} ]"
@@ -41,12 +41,11 @@ testSparseVolumeDoesNotCheckAvailableDiskSpace() {
     volume=$(docker volume create -d "${DRIVER}" -o fs=${FS} -o sparse=true -o size=10GiB)
     result=$?
 
-    info=$(ls --block-size=M -ls "/var/lib/${DRIVER}/${volume}.${FS}")
-    apparent_size=$(echo ${info} | awk '{print $6}' | tr -dc '0-9')
+    apparent_size="$(run stat -c '%s' ${DATA_DIR}/${volume}.${FS})"                       # apparent  space in bytes
 
     # checks
     assertEquals "0" "${result}"
-    assertEquals "10240" "${apparent_size}"
+    assertEquals "$((10*1024*1024*1024))" "${apparent_size}"
 
     # cleanup
     docker volume rm "${volume}" > /dev/null
@@ -56,9 +55,9 @@ testSparseVolumeDoesNotTakeDiskSpace() {
     local volume info allocated_size apparent_size
     # setup
     local volume=$(docker volume create -d "${DRIVER}" -o fs=${FS} -o sparse=true)
-    local info=$(ls --block-size=M -ls "/var/lib/${DRIVER}/${volume}.${FS}")
-    local allocated_size=$(echo ${info} | awk '{print $1}' | tr -dc '0-9')
-    local apparent_size=$(echo ${info} | awk '{print $6}' | tr -dc '0-9')
+
+    allocated_size="$(($(run stat -c '%b %B' ${DATA_DIR}/${volume}.${FS} | tr ' ' '*')))" # allocated space in bytes
+    apparent_size="$(run stat -c '%s' ${DATA_DIR}/${volume}.${FS})"                       # apparent  space in bytes
 
     # checks
     assertTrue "Sparse ${FS} volume of ${apparent_size} MiB should take less space: ${allocated_size} MiB" "[ ${allocated_size} -lt ${apparent_size} ]"

tests/test_volume_create_backing_fs.sh

@@ -12,7 +12,7 @@ testFallbackToDdFromFallocateOnUnsupportedFs() {
     result=$?
 
     ## because we shadow real data dir with our test volume we're sure there shouldn't be any volumes
-    count=$(ls -1 "/var/lib/${DRIVER}/" | grep -v "lost+found" | wc -l)
+    count=$(run ls -1 "${DATA_DIR}/" | grep -v "lost+found" | wc -l)
 
     assertEquals "Volume creation should succeed" "0" "${result}"
     assertEquals "There should be 1 volume" "1" "${count}"
@@ -30,7 +30,7 @@ testDdFailureScenarioWhenThereIsNotEnoughDiskSpace() {
     result=$?
 
     ## because we shadow real data dir with our test volume we're sure there shouldn't be any volumes
-    count=$(ls -1 "/var/lib/${DRIVER}/" | grep -v "lost+found" | wc -l)
+    count=$(run ls -1 "${DATA_DIR}/" | grep -v "lost+found" | wc -l)
 
     assertEquals "Volume creation should fail" "1" "${result}"
     assertEquals "There should be no volumes" "0" "${count}"