1. Introduction
In this article, we’ll learn how to check available disk space when using OverlayFS. First, let’s understand how OverlayFS works together with Docker. Then, we’ll review some commands that provide information about disk usage.
2. Understanding OverlayFS
Containers enable multiple isolated systems to run concurrently on top of a single operating system. For this, it uses an overlay file system called OverlayFS. The OverlayFS consists of layers: the lower layer is read-only, while the upper layer is read-write.
These layers also have directories, where OverlayFS refers to the lower directory as lowerdir and the upper directory as upperdir. Finally, the merged directory consolidates the contents of both underlying directories into a unified and consistent version.
Below, we can see how Docker builds its layers with the image and the container. The image layer (lowerdir) is the base layer, composed of the specifications included in the Dockerfile. It’s immutable and can be more than one, depending on the complexity of the image. Consequently, we can have several lowerdir:
Meanwhile, the container layer (upperdir) records all file system updates issued by the container to preserve the integrity of the image layers. In short, this is where any changes are stored, such as new or modified files, etc.
Finally, there’s the container’s mount point in the merged directory. This directory provides a unified view of the original files from lower directories alongside any changes or additions in the upper directories. Generally, we can understand that the merged directory forms the root of the container’s file system tree.
As shown in the figure, when reading the files, upperdir takes priority. This means that if a file exists in both layers, the OverlayFS prioritizes loading the one from the upper directory. Also, the file will load directly from its source if it belongs only to the image layer or the container layer.
Remember that deleting a file from the image layer creates a whiteout file in the upperdir. Because lowerdir is read-only, deleting the file is impossible. However, the whiteout file prevents it from becoming available.
3. Checking Disk Space on OverlayFS
Docker provides built-in commands to help analyze disk usage. The docker system df command gives an overview of disk usage by Docker:
$ docker system df
This command displays information about the amount of disk space used by images, containers, and others:
TYPE TOTAL ACTIVE SIZE RECLAIMABLE
Images 17 15 1.196GB 570.7MB (47%)
Containers 31 0 53.58MB 53.58MB (100%)
Local Volumes 8 2 1.653GB 1.235GB (74%)
Build Cache 67 0 25.99kB 25.99kB
The RECLAIMABLE column indicates the amount of disk space that can be potentially freed up by removing unused Docker objects (for instance, unused images or stopped containers).
Another command we can use is the df command, a standard Unix/Linux utility:
$ df -h
The -h flag makes the output human-readable, displaying sizes in MB or GB instead of blocks:
Filesystem Size Used Avail Use% Mounted on
tmpfs 391M 1,8M 389M 1% /run
/dev/vda3 24G 20G 3,1G 87% /
tmpfs 2,0G 0 2,0G 0% /dev/shm
tmpfs 5,0M 4,0K 5,0M 1% /run/lock
/dev/vda2 512M 6,1M 506M 2% /boot/efi
tmpfs 391M 116K 391M 1% /run/user/1000
overlay 24G 20G 3,1G 87% /var/lib/docker/overlay2/c49caf4c21324d27a5be076a5b0131f7cfb9b5200c0905190fa9fdb594013e3a/merged
overlay 24G 20G 3,1G 87% /var/lib/docker/overlay2/e446e8087dbd8270af8fc7f291003fa7744d436cb7f7442d32305928739d51b6/merged
The Filesystem column shows the devices or partitions on which the FS resides, as well as the system type. The tmpfs are temporary filesystems typically used for storing temporary files in memory (RAM). The /dev/vda are physical disk partitions. Finally, overlay refers to Docker’s OverlayFS storage controller.
In this case, we’ve two containers running, so the same number of merged directories is shown. Regarding disk usage, we have 24G total size, where 20G is being used and 3.1G is available to store files and use Docker.
4. Conclusion
In this article, we explored the mechanics of OverlayFS and learned how to check the available disk space.
When using Docker with OverlayFS, images, and containers are stored in layers. By leveraging tools like df and Docker’s own system commands, we can monitor the disk space on an OverlayFS filesystem.