Container Storage & UnionFS / Overlay2: How does the Copy-on-Write (CoW) mechanism work in Docker?

Architecture & Mechanics

Docker images are built as a stack of immutable, read-only layers. When a container runs, Docker attaches a single, thin, read-write layer on top known as the Container Layer. Docker implements this filesystem stack using the Overlay2 storage driver (Linux OverlayFS).

+-------------------------------------------------------+
| Container Read-Write Layer (Modified files, temp data)| <- "upperdir"
+-------------------------------------------------------+
| Layer 3: Application Code (Read-Only)                 | \
+-------------------------------------------------------+  |
| Layer 2: Installed Runtime / Node / Python (Read-Only)|  | <- "lowerdir" (Immutable image layers)
+-------------------------------------------------------+  |
| Layer 1: Base OS Debian/Alpine (Read-Only)            | /
+-------------------------------------------------------+
                          |
                          v
         [ Merged View (What the container sees) ]

OverlayFS Directory Structure

1. lowerdir: The read-only base image layers joined together with colon-separated paths.
2. upperdir: The writable container layer where file modifications, new files, and deletes are recorded.
3. workdir: Internal scratch directory used by the Linux kernel to prepare atomic copy-on-write operations.
4. merged: The unified mount point presented to the container process.

Copy-on-Write (CoW) Lifecycle

• Reading a file: The driver checks upperdir. If the file is not there, it reads down into lowerdir with zero performance penalty.
• Modifying an existing file: The first time a container writes to a file that belongs to a read-only lower layer, the kernel copies the entire file up to upperdir (copy-on-write) and applies edits there. The original layer remains completely untouched.
• Deleting a file: A special whiteout character device file is written to upperdir, hiding the file in the merged view without deleting it from the underlying immutable layer.
• Production Implication: High-I/O workloads (databases, message brokers) should never write directly to the container layer; they should always write to Docker Volumes or mounted block storage to bypass the CoW overhead.