OverlayFS Performance Considerations and Best Practices

to. Subsequent writes to the same file operate against the copy of the file already copied up to the container. - OverlayFS works with multiple layers. This means that performance can be impacted when searching for files in images with many layers. #### Deleting files and directories - When a _file_ is deleted within a container, a _whiteout_ file is created in the container (`upperdir`). The version of the file in the image layer (`lowerdir`) is not deleted (because the `lowerdir` is read-only). However, the whiteout file prevents it from being available to the container. - When a _directory_ is deleted within a container, an _opaque directory_ is created within the container (`upperdir`). This works in the same way as a whiteout file and effectively prevents the directory from being accessed, even though it still exists in the image (`lowerdir`). #### Renaming directories Calling `rename(2)` for a directory is allowed only when both the source and the destination path are on the top layer. Otherwise, it returns `EXDEV` error ("cross-device link not permitted"). Your application needs to be designed to handle `EXDEV` and fall back to a "copy and unlink" strategy. ## OverlayFS and Docker Performance `overlay2` may perform better than `btrfs`. However, be aware of the following details: ### Page caching OverlayFS supports page cache sharing. Multiple containers accessing the same file share a single page cache entry for that file. This makes the `overlay2` drivers efficient with memory and a good option for high-density use cases such as PaaS. ### Copyup As with other copy-on-write filesystems, OverlayFS performs copy-up operations whenever a container writes to a file for the first time. This can add latency into the write operation, especially for large files. However, once the file has been copied up, all subsequent writes to that file occur in the upper layer, without the need for further copy-up operations. ### Performance best practices The following generic performance best practices apply to OverlayFS. #### Use fast storage Solid-state drives (SSDs) provide faster reads and writes than spinning disks.

This section details performance aspects of the OverlayFS storage driver in Docker. It explains that while `overlay2` may outperform `btrfs`, initial writes to files trigger a 'copy-up' operation, potentially causing latency, especially with large files. Subsequent writes are faster as they occur in the upper layer. OverlayFS supports page cache sharing, making it memory-efficient. For best performance, use fast storage like SSDs, as they offer faster reads and writes. When deleting files, 'whiteout' files are created in the upper layer, while deleting directories results in 'opaque directories.' Renaming a directory requires source and destination paths to be on the top layer to avoid the EXDEV error, necessitating a 'copy and unlink' strategy in such cases.