Docker volume mounts

site/content/post/2019-04-01-understanding-docker-volume-mounts.md

@@ -0,0 +1,221 @@
+---
+date: 2019-04-01
+title: Understanding Docker volume mounts
+url: /2019/04/01/understanding-docker-volume-mounts/
+image: /res/images/docker/logo.png
+description: It's basically magic.
+---
+
+One thing that always confuses me with Docker is how exactly mounting
+volumes behaves. At a basic level it's fairly straight forward: you
+declare a volume in a Dockerfile, and then either explicitly mount
+something there or docker automatically creates an anonymous volume
+for you. Done. But it turns out there's quite a few edge cases...
+
+<!--more-->
+
+### Changing ownership of the folder
+
+Perhaps the most common operation done on a Docker volume other than
+simply mounting it is trying to change the ownership of the directory.
+If your Docker process runs as a certain user you probably want the
+directory to be writable by that user.
+
+At first we might try something like:
+
+{{< highlight docker >}}
+FROM alpine
+RUN adduser -D -u 1113 test123
+USER test123
+VOLUME /testing
+{{< / highlight >}}
+
+But changing the user doesn't seem to have any effect on the volume.
+Why? Checking the docs for the 
+[`USER` instruction](https://docs.docker.com/engine/reference/builder/#user)
+shows that only affects certain future operations -- namely
+`RUN`, `CMD`, and `ENTRYPOINT`. It doesn't affect the `VOLUME` instruction;
+if it did, you'd probably just get a permission denied error unless the user
+you switch to had privileges to create mount points.
+
+OK, so instead we might try using the good old `chown` command:
+
+{{< highlight docker >}}
+FROM alpine
+RUN adduser -D -u 1113 test123
+VOLUME /testing
+RUN chown test123 /testing
+{{< / highlight >}}
+
+But again, the directory is just owned by root at runtime.
+Back to the docs, this time for the
+[`VOLUME` instruction](https://docs.docker.com/engine/reference/builder/#volume)
+and towards the bottom is this little tidbit:
+
+> Changing the volume from within the Dockerfile: If any build steps change
+> the data within the volume after it has been declared, those changes will
+> be discarded.
+
+As soon as Docker hits `VOLUME` instruction, the directory becomes a mount
+point, and anything we do to the temporary volume mounted there is discarded
+during the build process. So we have to change the ownership *before* the
+instruction, which may seem a little counter-intuitive:
+
+{{< highlight docker >}}
+FROM alpine
+RUN adduser -D -u 1113 test123
+RUN mkdir /testing && chown test123 /testing
+VOLUME /testing
+{{< / highlight >}}
+
+Now when the container runs, the /testing directory is owned by the test123
+user. It's not quite over, yet, though. This works if we let Docker create
+a volume automatically for us, or if we create a named volume and mount that;
+if we try and mount a host directory, though, it falls flat:
+
+{{< highlight console >}}
+$ docker run --rm -it -v "$PWD/testing:/testing" testing ls -al /testing
+total 8
+drwxr-xr-x    2 1000     1000          4096 Apr  1 19:39 .
+drwxr-xr-x    1 root     root          4096 Apr  1 20:44 ..
+{{< / highlight >}}
+
+Docker handles mounting host directories differently to mounting volumes,
+even though the syntax is basically the same. Host directories are bind
+mounted directly into the container, so the permissions and ownership
+are the same as the directory on your host. The only way to fix them are
+to either change the permissions on the host, or have the container
+change them at runtime (assuming it has sufficient privileges).
+
+One final wrinkle in all this happens when you use the same container
+in multiple containers. Here we have two images built from the
+Dockerfile above, one with userid 1113 and one with userid 1114:
+
+{{< highlight console >}}
+$ docker volume create testing
+testing
+
+$ docker run --rm -it -v testing:/testing testing1113 ls -nal /testing
+total 8
+drwxr-xr-x    2 1113     0             4096 Apr  1 19:49 .
+drwxr-xr-x    1 0        0             4096 Apr  1 20:51 ..
+
+$ docker run --rm -it -v testing:/testing testing1114 ls -nal /testing
+total 8
+drwxr-xr-x    2 1114     0             4096 Apr  1 20:47 .
+drwxr-xr-x    1 0        0             4096 Apr  1 20:52 ..
+
+$ docker run --rm -it -v testing:/testing testing1114 touch /testing/Hello
+
+$ docker run --rm -it -v testing:/testing testing1113 ls -nal /testing
+total 8
+drwxr-xr-x    2 1114     0             4096 Apr  1 20:52 .
+drwxr-xr-x    1 0        0             4096 Apr  1 20:53 ..
+-rw-r--r--    1 0        0                0 Apr  1 20:52 Hello
+
+$ docker run --rm -it -v testing:/testing testing1114 ls -nal /testing
+total 8
+drwxr-xr-x    2 1114     0             4096 Apr  1 20:52 .
+drwxr-xr-x    1 0        0             4096 Apr  1 20:52 ..
+-rw-r--r--    1 0        0                0 Apr  1 20:52 Hello
+{{< / highlight >}}
+
+Can you see what's going on? When the volume is empty, the ownership
+changes based on the mount point in the container. Once it has something
+in it, the ownership is fixed.
+
+So Docker behaves differently with regard to permissions:
+
+ * when the folder is mounted from the host vs a volume
+ * when the volume is empty vs having content
+
+### Pre-populating mounts with files from the image
+
+One of the more esoteric features of the way Docker handles volume
+mounts is that in some cases files from the image are copied over
+into the container. For example:
+
+{{< highlight console >}}
+$ docker volume create testing
+testing
+
+$ docker run --rm -it -v testing:/etc testing sleep 1
+
+$ docker run --rm -it -v testing:/tmp testing ls -al /tmp
+total 184
+drwxr-xr-x   15 root     root          4096 Apr  1 20:58 .
+drwxr-xr-x    1 root     root          4096 Apr  1 20:59 ..
+-rw-r--r--    1 root     root             4 Jun  7  2018 TZ
+-rw-r--r--    1 root     root             6 Dec 20 21:31 alpine-release
+...
+{{< / highlight >}}
+
+The first container we run mounts the newly created `testing` volume
+at `/etc`. Docker copies all the existing files and folders into the
+volume; when we then run the second container with the volume mounted
+at `/tmp`, we can see all of the files that were in the first container's
+`/etc`.
+
+As with permissions, this behaviour is anything but consistent. Say we
+switch from a volume to a host directory:
+
+{{< highlight console >}}
+$ mkdir testing
+$ docker run --rm -it -v "$PWD/testing:/usr/bin" testing sleep 1
+$ ls -al testing
+total 8
+drwxr-xr-x 2 root  root  4096 Apr  1 22:05 .
+drwxr-xr-x 3 chris chris 4096 Apr  1 22:05 ..
+{{< / highlight >}}
+
+Nothing is copied in, and inside the container the folder will be empty.
+Based on our discoveries with permisions, it's reasonable to assume the
+same will happy with a non-empty volume too:
+
+{{< highlight console >}}
+$ docker volume create testing
+testing
+
+$ docker run --rm -it -v testing:/testing testing touch /testing/Hello
+
+$ docker run --rm -it -v testing:/usr/bin testing sleep 1
+
+$ docker run --rm -it -v testing:/tmp testing ls -al /tmp
+total 8
+drwxr-xr-x    2 root     root          4096 Apr  1 21:09 .
+drwxr-xr-x    1 root     root          4096 Apr  1 21:09 ..
+-rw-r--r--    1 root     root             0 Apr  1 21:08 Hello
+{{< / highlight >}}
+
+So at least that's consistent. If you're very observant, though, you
+might notice I switched from `/etc/` to `/usr/bin` in the examples.
+That's because within the container `/etc/` has some files bind-mounted
+into it, such as `/etc/resolv.conf`, and these *do* always result in files
+being created in the mounted volumes or folders:
+
+{{< highlight console >}}
+$ mkdir testing
+$ docker run --rm -it -v "$PWD/testing:/etc" testing sleep 1
+$ ls -al testing
+total 8
+drwxr-xr-x 2 chris chris 4096 Apr  1 22:12 .
+drwxr-xr-x 3 chris chris 4096 Apr  1 22:12 ..
+-rwxr-xr-x 1 root  root     0 Apr  1 22:12 hostname
+-rwxr-xr-x 1 root  root     0 Apr  1 22:12 hosts
+-rwxr-xr-x 1 root  root     0 Apr  1 22:12 resolv.conf
+{{< / highlight >}}
+
+### Summary
+
+ * Docker treats mounting host folders and mounting volumes differently.
+   Don't just assume that you can swap one for another and get the exact
+   same behaviour.
+ * Empty volumes will inherit permissions and files from the image
+   they are mounted in; non-empty volumes and host folders will not.
+ * Relying on Docker copying files into volumes is a very bad idea,
+   as if you change those files in a future version of your image
+   they will not be copied unless the volume is deleted and
+   recreated.
+
+I can't find anywhere that these points are documented properly;
+if you know of anywhere, please drop me a message!