An Image is an ordered collection of root filesystem changes and the corresponding execution parameters for use within a container runtime. This specification outlines the format of these filesystem changes and corresponding parameters and describes how to create and use them for use with a container runtime and execution tool.
This specification uses the following terms:
Here is an example image JSON file:
{
"id": "a9561eb1b190625c9adb5a9513e72c4dedafc1cb2d4c5236c9a6957ec7dfd5a9",
"parent": "c6e3cedcda2e3982a1a6760e178355e8e65f7b80e4e5248743fa3549d284e024",
"checksum": "tarsum.v1+sha256:e58fcf7418d2390dec8e8fb69d88c06ec07039d651fedc3aa72af9972e7d046b",
"created": "2014-10-13T21:19:18.674353812Z",
"author": "Alyssa P. Hacker <alyspdev@example.com>",
"architecture": "amd64",
"os": "linux",
"Size": 271828,
"config": {
"User": "alice",
"Memory": 2048,
"MemorySwap": 4096,
"CpuShares": 8,
"ExposedPorts": {
"8080/tcp": {}
},
"Env": [
"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
"FOO=docker_is_a_really",
"BAR=great_tool_you_know"
],
"Entrypoint": [
"/bin/my-app-binary"
],
"Cmd": [
"--foreground",
"--config",
"/etc/my-app.d/default.cfg"
],
"Volumes": {
"/var/job-result-data": {},
"/var/log/my-app-logs": {},
},
"WorkingDir": "/home/alice",
}
}
Any extra fields in the Image JSON struct are considered implementation specific and should be ignored by any implementations which are unable to interpret them.
An example of creating an Image Filesystem Changeset follows.
An image root filesystem is first created as an empty directory named with the ID of the image being created. Here is the initial empty directory structure for the changeset for an image with ID c3167915dc9d (real IDs are much longer, but this example use a truncated one here for brevity. Implementations need not name the rootfs directory in this way but it may be convenient for keeping record of a large number of image layers.):
c3167915dc9d/
Files and directories are then created:
c3167915dc9d/
etc/
my-app-config
bin/
my-app-binary
my-app-tools
The c3167915dc9d directory is then committed as a plain Tar archive with entries for the following files:
etc/my-app-config bin/my-app-binary bin/my-app-tools
The TarSum checksum for the archive file is then computed and placed in the JSON metadata along with the execution parameters.
To make changes to the filesystem of this container image, create a new directory named with a new ID, such as f60c56784b83, and initialize it with a snapshot of the parent image's root filesystem, so that the directory is identical to that of c3167915dc9d. NOTE: a copy-on-write or union filesystem can make this very efficient:
f60c56784b83/
etc/
my-app-config
bin/
my-app-binary
my-app-tools
This example change is going to add a configuration directory at /etc/my-app.d which contains a default config file. There's also a change to the my-app-tools binary to handle the config layout change. The f60c56784b83 directory then looks like this:
f60c56784b83/
etc/
my-app.d/
default.cfg
bin/
my-app-binary
my-app-tools
This reflects the removal of /etc/my-app-config and creation of a file and directory at /etc/my-app.d/default.cfg. /bin/my-app-tools has also been replaced with an updated version. Before committing this directory to a changeset, because it has a parent image, it is first compared with the directory tree of the parent snapshot, f60c56784b83, looking for files and directories that have been added, modified, or removed. The following changeset is found:
Added: /etc/my-app.d/default.cfg Modified: /bin/my-app-tools Deleted: /etc/my-app-config
A Tar Archive is then created which contains only this changeset: The added and modified files and directories in their entirety, and for each deleted item an entry for an empty file at the same location but with the basename of the deleted file or directory prefixed with .wh.. The filenames prefixed with .wh. are known as “whiteout” files. NOTE: For this reason, it is not possible to create an image root filesystem which contains a file or directory with a name beginning with .wh.. The resulting Tar archive for f60c56784b83 has the following entries:
/etc/my-app.d/default.cfg /bin/my-app-tools /etc/.wh.my-app-config
Any given image is likely to be composed of several of these Image Filesystem Changeset tar archives.
There is also a format for a single archive which contains complete information about an image, including:
For example, here's what the full archive of library/busybox is (displayed in tree format):
. ├── 5785b62b697b99a5af6cd5d0aabc804d5748abbb6d3d07da5d1d3795f2dcc83e │ ├── VERSION │ ├── json │ └── layer.tar ├── a7b8b41220991bfc754d7ad445ad27b7f272ab8b4a2c175b9512b97471d02a8a │ ├── VERSION │ ├── json │ └── layer.tar ├── a936027c5ca8bf8f517923169a233e391cbb38469a75de8383b5228dc2d26ceb │ ├── VERSION │ ├── json │ └── layer.tar ├── f60c56784b832dd990022afc120b8136ab3da9528094752ae13fe63a2d28dc8c │ ├── VERSION │ ├── json │ └── layer.tar └── repositories
There are one or more directories named with the ID for each layer in a full image. Each of these directories contains 3 files:
VERSION - The schema version of the json filejson - The JSON metadata for an image layerlayer.tar - The Tar archive of the filesystem changeset for an image layer.The content of the VERSION files is simply the semantic version of the JSON metadata schema:
1.0
And the repositories file is another JSON file which describes names/tags:
{
"busybox":{
"latest":"5785b62b697b99a5af6cd5d0aabc804d5748abbb6d3d07da5d1d3795f2dcc83e"
}
}
Every key in this object is the name of a repository, and maps to a collection of tag suffixes. Each tag maps to the ID of the image represented by that tag.
Unpacking a bundle of image layer JSON files and their corresponding filesystem changesets can be done using a series of steps:
Follow the parent IDs of image layers to find the root ancestor (an image with no parent ID specified).
For every image layer, in order from root ancestor and descending down, extract the contents of that layer's filesystem changeset archive into a directory which will be used as the root of a container filesystem.
.wh. and the corresponding file or directory named without this prefix.This specification is an admittedly imperfect description of an imperfectly-understood problem. The Docker project is, in turn, an attempt to implement this specification. Our goal and our execution toward it will evolve over time, but our primary concern in this specification and in our implementation is compatibility and interoperability.