How are docker images built? A look into the Linux overlay file-systems and the OCI specification

What’s an overlay filesystems

Create an overlay fs

[2020-04-19 16:02:35] [ubuntu] [/tmp/overlay-example]  
> mkdir mount layer-1 layer-2 layer-3 layer-4 workdir
[2020-04-19 16:02:38] [ubuntu] [/tmp/overlay-example]
> ls
layer-1 layer-2 layer-3 layer-4 mount workdir
[2020-04-19 16:02:40] [ubuntu] [/tmp/overlay-example]  
> echo "Layer-1 file" > ./layer-1/some-file-in-layer-1
[2020-04-19 16:03:36] [ubuntu] [/tmp/overlay-example]
> echo "Layer-2 file" > ./layer-2/some-file-in-layer-2
[2020-04-19 16:03:53] [ubuntu] [/tmp/overlay-example]
> echo "Layer-3 file" > ./layer-3/some-file-in-layer-3
> sudo mount -t overlay overlay-example \ -o lowerdir =/tmp/overlay-example/layer-1:/tmp/overlay-example/layer-2:/tmp/overlay-example/layer-3,upperdir=/tmp/overlay-example/layer-4,workdir=/tmp/overlay-example/workdir \ /tmp/overlay-example/mount
[2020-04-19 16:13:33] [ubuntu] [/tmp/overlay-example/mount] > cat some-file-in-layer-3 
Layer-3 file
[2020-04-19 16:23:31] [ubuntu] [/tmp/overlay-example/mount]  
> echo "new content" > new-file

[2020-04-19 16:27:33] [ubuntu] [/tmp/overlay-example/mount]
> ls
new-file some-file-in-layer-1 some-file-in-layer-2 some-file-in-layer-3
[2020-04-19 16:23:49] [ubuntu] [/tmp/overlay-example]  
> tree
.
├── layer-1
│ └── some-file-in-layer-1
├── layer-2
│ └── some-file-in-layer-2
├── layer-3
│ └── some-file-in-layer-3
├── layer-4
│ └── new-file
├── mount
│ ├── new-file
│ ├── some-file-in-layer-1
│ ├── some-file-in-layer-2
│ └── some-file-in-layer-3
└── workdir
└── work [error opening dir]
7 directories, 8 files
[2020-04-19 16:27:33] [ubuntu] [/tmp/overlay-example/mount] > rm some-file-in-layer-2 
[2020-04-19 16:28:58] [ubuntu] [/tmp/overlay-example/mount] > ls
new-file some-file-in-layer-1 some-file-in-layer-3
[2020-04-19 16:29:57] [ubuntu] [/tmp/overlay-example]  
> tree
.
├── layer-1
│ └── some-file-in-layer-1
├── layer-2
│ └── some-file-in-layer-2
├── layer-3
│ └── some-file-in-layer-3
├── layer-4
│ ├── new-file
│ └── some-file-in-layer-2
├── mount
│ ├── new-file
│ ├── some-file-in-layer-1
│ └── some-file-in-layer-3
└── workdir
└── work [error opening dir]
7 directories, 8 files
[2020-04-19 16:31:09] [ubuntu] [/tmp/overlay-example/layer-4]  
> ls -la
total 12
drwxr-xr-x 2 napicell domain^users 4096 Apr 19 16:28 .
drwxr-xr-x 8 napicell domain^users 4096 Apr 19 16:07 ..
-rw-r--r-- 1 napicell domain^users 12 Apr 19 16:23 new-file
c--------- 1 root root 0, 0 Apr 19 16:28 some-file-in-layer-2
[2020-04-19 16:37:11] [ubuntu] [/tmp/overlay-example]  
> sudo umount /tmp/overlay-example/mount && rm -rf /tmp/overlay-example

Wrapping up the overlay filesystems

What’s a docker Image?

Layers cache

OCI-format container images

Other overlay filesystems

What happens when you build an image?

  1. Docker downloads the tarball for the image specified in the “FROM” and unpacks it. This is the first layer of the image.
  2. Mounts a union file system, with the lower dir being the one just downloaded. The upper dir is an empty folder
  3. Starts bash in a chroot and runs the command specified in RUN: chroot . /bin/bash -c “apt get update”
  4. When the command is over, it zips the upper layer. This is the new layer of the image we are building
  5. If the dockerfile contains other commands, repeat the process from the second step using as lower dir all the layers we have got so far. Otherwise exit.

Conclusion

--

--

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Nicola Apicella

Nicola Apicella

Sr. software dev engineer at Amazon. Golang, Java and container enthusiast. Love automation in general. Opinions are my own.