Docker overlay2 스토리지｜이미지 레이어가 합쳐지는 방식
Docker’s overlay2 uses OverlayFS to combine read-only image layers (lowerdir) with a container-specific writable layer (upperdir) into a single unified mount point (merged) that the container uses as its root filesystem. Writes that occur inside a container do not persist to the underlying image, and when a container is removed, its writable layer is permanently destroyed along with it. This is part 3 of 4 in the Docker series, covering how container and image layers are combined on disk based on official storage driver documentation. Part 2 covered docker load, docker save, and docker run; part 4 will address layer caching, volumes, and bind mounts in practice.
What is the relationship between the storage driver and image layers?
Short answer: The storage driver manages the stacked read-only layers that make up an image and adds a new writable layer on top when a container is created, presenting a unified filesystem view to the container.
A Docker image is not a single flat file. It is a stack of immutable, read-only layers, where each layer corresponds to an instruction in the Dockerfile (such as FROM, RUN, or COPY). Because these layers are read-only, they can be safely shared between multiple containers that use the same base image.
The storage driver is the component responsible for managing this layer stack and presenting it to the container runtime as a single coherent filesystem. When a container is created, the storage driver adds a new writable layer on top of the read-only image layers. The container then sees a merged view of all those layers.
Docker overlay2 is the storage driver that leverages the Linux kernel’s OverlayFS filesystem. It is the widely-used default driver on Linux hosts according to the official documentation. overlay2 represents image layers as the lowerdir and the container’s writable layer as the upperdir, then exposes the merged mountpoint as the container’s root filesystem.
Regardless of how an image was obtained — whether via docker pull, docker load (covered in part 2), or a local build — the storage driver applies the same layering process when a container is created.
What are lowerdir, upperdir, merged, and workdir in overlay2?
Short answer: lowerdir holds the read-only image layers, upperdir is the container’s writable layer, merged is the unified view the container sees, and workdir is an internal scratch directory required by OverlayFS.
OverlayFS is a Linux kernel filesystem that overlays multiple directories into one unified view. In overlay2, four components work together to present a single filesystem to the container.
| Component | Role | Access |
|---|---|---|
| lowerdir | The read-only image layers. Multiple lower layers are supported, corresponding to the stacked layers of the Docker image. The container cannot write to these layers directly. | Read-only |
| upperdir | The writable container layer created when the container starts. All file changes made inside the container (creates, modifications, deletions) are recorded here. | Read-write |
| merged | The unified view that combines the upperdir and lowerdir layers. This is the root filesystem (/) that the container process sees. | Unified view |
| workdir | An internal scratch directory required by OverlayFS to perform atomic copy-up operations. It is not directly visible to or usable by container processes. | Internal only |
From the container’s perspective, the merged mountpoint looks like a complete, ordinary filesystem. If a file exists in both upperdir and lowerdir, the upperdir version takes precedence. Files that exist only in lowerdir are transparently surfaced through the merged view. This means the container can read files from the image layers without any special handling — they simply appear in place.
When an image has many layers (as built from a multi-stage or multi-instruction Dockerfile), all those layers appear as entries in the lowerdir. overlay2 supports multiple lower layers, so this multi-layer stack is represented in a single OverlayFS mount.
Note: Starting with Docker Engine 29, the containerd image store (snapshotter) may be used by default. The fundamental concept of stacked layers remains the same, but the actual paths and management commands can differ. The explanations in this article are based on the classic overlay2 model as described in the official Docker storage driver documentation.
What does copy-on-write do when a file is modified?
Short answer: When a file that exists only in the lowerdir is first modified, OverlayFS copies the entire file up to the upperdir (copy-up) before applying the modification. Deleting a file from the lowerdir creates a whiteout entry in the upperdir that hides the original without removing it from the read-only layer.
Copy-on-write (CoW) is the mechanism that allows containers to modify files from read-only image layers without altering those layers. In overlay2, CoW works as follows.
Modifying a file: copy-up
When a container process attempts to modify a file that exists only in the lowerdir, OverlayFS performs a copy-up operation before the write takes place.
- The entire file is copied from the lowerdir to the upperdir.
- The write is then applied to the copy in the upperdir.
- The original file in the lowerdir remains unchanged.
Copy-up incurs an upfront cost proportional to the size of the file being modified. However, subsequent writes to the same file go directly to the upperdir copy without any additional copy-up. The official documentation notes that this initial copy cost can affect performance for write-heavy workloads — a point addressed in the next section.
Deleting a file: whiteout
When a container deletes a file that exists in the lowerdir, OverlayFS does not modify the read-only layer. Instead, it creates a special whiteout file (or an opaque attribute for directories) in the upperdir at the same path. This whiteout entry instructs the merged view to hide the corresponding lowerdir entry, making the file appear deleted to the container. The original file in the lowerdir is never touched, preserving the layer’s immutability.
Creating a new file
When a container creates a new file that does not exist in any lowerdir, the file is written directly to the upperdir without any copy-up step.
How is disk space shared when multiple containers use the same image?
Short answer: Multiple containers based on the same image share the underlying read-only image layers (lowerdir) on the host. Each container creates only its own thin upperdir, so disk usage does not multiply with the number of containers.
Layer sharing is one of the key efficiency benefits of the overlay2 storage model. Consider running ten containers from the same base image.
- Image layers (lowerdir): The image layers are stored only once on the host. All ten containers reference those same layers simultaneously. No additional copy of the image data is created on disk for each container.
- Container writable layer (upperdir): Each container gets its own upperdir. If a container writes nothing, its upperdir remains nearly empty. Only the files that have been modified or created within that specific container accumulate in its upperdir.
According to the official storage driver documentation, this sharing means that running many containers from the same image does not cause disk usage to grow linearly with the container count. Similarly, when pulling an image, any layers already present locally are not downloaded again, reducing both bandwidth and pull time.
This sharing is safe because the lowerdir is strictly read-only. No container can directly modify the image layers, so all containers can reference the same lowerdir without risk of data corruption between them.
Why is it problematic to store write-heavy data in the overlay writable layer?
Short answer: The writable layer is permanently destroyed when the container is removed, and placing write-heavy data there incurs copy-up performance overhead. Persistent or I/O-intensive data should use Docker volumes or bind mounts instead.
The writable layer is destroyed when the container is removed
When a container is removed with docker rm, its upperdir and all data written to it are permanently deleted. The image layers (lowerdir) are unaffected. This means any data written exclusively to the container’s writable layer during its lifetime is irrecoverably lost when the container is removed. This is by design: the immutability of image layers depends on the writable layer being separate and disposable.
Performance overhead for write-heavy workloads
The official Docker storage driver documentation explicitly advises against placing write-heavy workloads in the container’s writable layer. Two factors contribute to the performance concern.
- Copy-up cost: Every file from the lowerdir that is modified for the first time must be fully copied to the upperdir before the write can proceed. For large files, this initial copy is non-trivial.
- Layer traversal overhead: Looking up a file requires OverlayFS to search the upperdir and then each lowerdir in order. Images with many layers increase this traversal path.
Use volumes or bind mounts for persistent or I/O-intensive data
For data that must survive container removal — such as database files, application logs, or caches — or for workloads with high I/O rates, Docker volumes and bind mounts are the correct solution. Unlike the overlay writable layer, volumes and bind mounts bypass the OverlayFS stack and read and write directly to the host filesystem. Volume data persists independently of the container lifecycle.
The detailed mechanics of volumes and bind mounts, as well as layer cache strategies, are covered in part 4 of this series. The essential principle to take away from this section is: the overlay writable layer is ephemeral by design, so any data that needs to outlive the container must be placed on an external mount.
FAQ
Short answer: Common questions about the overlay2 storage driver.
| Question | Answer |
|---|---|
| How do I check which storage driver is currently in use? | Run docker info and look for the Storage Driver field. On a typical Linux host it will read overlay2. |
| What should I be aware of when changing the storage driver? | Changing the storage driver can make existing local images and containers inaccessible, because the new driver cannot read data stored by the previous driver. Before switching, back up any images you need using docker save (see part 2 of this series). Consult the official documentation and your host environment before making any changes. |
| On Docker Engine 29+, will the overlay2 paths look different? | Docker Engine 29 and later may use the containerd image store (snapshotter) by default. The concept of stacked layers is the same, but the actual storage paths and management commands can differ from the classic overlay2 model. Run docker info to check your current configuration before drawing conclusions about paths or layer layout. |
| Are files written inside a container reflected back to the image? | No. Writes go to the container’s upperdir only. The image layers (lowerdir) are never modified. To persist changes to a new image, use docker commit or build a new image with a Dockerfile. |
| Are there storage drivers other than overlay2? | Yes. The official documentation also covers btrfs, zfs, the legacy devicemapper, and vfs. However, overlay2 is the recommended default for Linux hosts. The appropriate driver depends on the host filesystem and kernel version. |
References
Short answer: Facts in this article are drawn from Docker’s official storage driver documentation checked on 2026-09-14.
- Use the OverlayFS storage driver — Docker Docs — Used to verify lowerdir, upperdir, merged, and workdir terminology, copy-up behavior, whiteout, and layer sharing.
- Storage drivers overview — Docker Docs — Used to verify the storage driver’s role, the copy-on-write overview, and the official recommendation to use volumes for write-heavy workloads.
- Manage data in Docker — Docker Docs — Referenced for the overall container storage model and the introduction to volumes and bind mounts.
This article is a general overview based on Docker’s official storage driver documentation. Actual paths and management commands can vary depending on the Docker Engine version, whether the containerd image store is in use, and the host filesystem.