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:

Docker OverlayFS

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.