Image and Container Layers: Structure and Access

Each image layer has its own directory within `/var/lib/docker/overlay/`, which contains its contents, as shown in the following example. The image layer IDs don't correspond to the directory IDs. > [!WARNING] > > Don't directly manipulate any files or directories within > `/var/lib/docker/`. These files and directories are managed by Docker. ```console $ ls -l /var/lib/docker/overlay/ total 20 drwx------ 3 root root 4096 Jun 20 16:11 38f3ed2eac129654acef11c32670b534670c3a06e483fce313d72e3e0a15baa8 drwx------ 3 root root 4096 Jun 20 16:11 55f1e14c361b90570df46371b20ce6d480c434981cbda5fd68c6ff61aa0a5358 drwx------ 3 root root 4096 Jun 20 16:11 824c8a961a4f5e8fe4f4243dab57c5be798e7fd195f6d88ab06aea92ba931654 drwx------ 3 root root 4096 Jun 20 16:11 ad0fe55125ebf599da124da175174a4b8c1878afe6907bf7c78570341f308461 drwx------ 3 root root 4096 Jun 20 16:11 edab9b5e5bf73f2997524eebeac1de4cf9c8b904fa8ad3ec43b3504196aa3801 ``` The image layer directories contain the files unique to that layer as well as hard links to the data shared with lower layers. This allows for efficient use of disk space. ```console $ ls -i /var/lib/docker/overlay2/38f3ed2eac129654acef11c32670b534670c3a06e483fce313d72e3e0a15baa8/root/bin/ls 19793696 /var/lib/docker/overlay2/38f3ed2eac129654acef11c32670b534670c3a06e483fce313d72e3e0a15baa8/root/bin/ls $ ls -i /var/lib/docker/overlay2/55f1e14c361b90570df46371b20ce6d480c434981cbda5fd68c6ff61aa0a5358/root/bin/ls 19793696 /var/lib/docker/overlay2/55f1e14c361b90570df46371b20ce6d480c434981cbda5fd68c6ff61aa0a5358/root/bin/ls ``` #### The container layer Containers also exist on-disk in the Docker host's filesystem under `/var/lib/docker/overlay/`. If you list a running container's subdirectory using the `ls -l` command, three directories and one file exist: ```console $ ls -l /var/lib/docker/overlay2/<directory-of-running-container> total 16 -rw-r--r-- 1 root root 64 Jun 20 16:39 lower-id drwxr-xr-x 1 root root 4096 Jun 20 16:39 merged drwxr-xr-x 4 root root 4096 Jun 20 16:39 upper drwx------ 3 root root 4096 Jun 20 16:39 work ``` The `lower-id` file contains the ID of the top layer of the image the container is based on, which is the OverlayFS `lowerdir`. ```console $ cat /var/lib/docker/overlay2/ec444863a55a9f1ca2df72223d459c5d940a721b2288ff86a3f27be28b53be6c/lower-id 55f1e14c361b90570df46371b20ce6d480c434981cbda5fd68c6ff61aa0a5358 ``` The `upper` directory contains the contents of the container's read-write layer, which corresponds to the OverlayFS `upperdir`. The `merged` directory is the union mount of the `lowerdir` and `upperdirs`, which comprises the view of the filesystem from within the running container. The `work` directory is internal to OverlayFS. To view the mounts which exist when you use the `overlay2` storage driver with Docker, use the `mount` command. The following output is truncated for readability. ```console $ mount | grep overlay overlay on /var/lib/docker/overlay2/l/ec444863a55a.../merged type overlay (rw,relatime,lowerdir=/var/lib/docker/overlay2/l/55f1e14c361b.../root, upperdir=/var/lib/docker/overlay2/l/ec444863a55a.../upper, workdir=/var/lib/docker/overlay2/l/ec444863a55a.../work) ``` The `rw` on the second line shows that the `overlay` mount is read-write. ## How container reads and writes work with `overlay2` <a name="how-container-reads-and-writes-work-with-overlay-or-overlay2"></a> ### Reading files Consider three scenarios where a container opens a file for read access with overlay. #### The file does not exist in the container layer If a container opens a file for read access and the file does not already exist in the container (`upperdir`) it is read from the image (`lowerdir`). This incurs very little performance overhead. #### The file only exists in the container layer If a container opens a file for read access and the file exists in the container (`upperdir`) and not in the image (`lowerdir`), it's read directly from the container. #### The file exists in both the container layer and the image layer

This section details the structure of image and container layers on the Docker host's filesystem under `/var/lib/docker/overlay2/`. It explains that each image layer has its directory containing its contents and hard links for shared data, optimizing disk usage. It further elucidates the container layer's structure, including the `lower-id` file pointing to the base image layer, the `upper` directory for the container's read-write layer, the `merged` directory for the combined filesystem view, and the `work` directory for OverlayFS internals. It concludes with explanations of how container reads and writes work, detailing file access scenarios from the container layer or image layer.