moby/image/spec/v1.2.md

Docker Image Specification v1.2.0

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 version of the image specification was adopted starting in Docker 1.12.

Terminology

This specification uses the following terms:

Layer

Images are composed of layers. Each layer is a set of filesystem changes. Layers do not have configuration metadata such as environment variables or default arguments - these are properties of the image as a whole rather than any particular layer.

Image JSON

Each image has an associated JSON structure which describes some basic information about the image such as date created, author, and the ID of its parent image as well as execution/runtime configuration like its entry point, default arguments, CPU/memory shares, networking, and volumes. The JSON structure also references a cryptographic hash of each layer used by the image, and provides history information for those layers. This JSON is considered to be immutable, because changing it would change the computed ImageID. Changing it means creating a new derived image, instead of changing the existing image.

Image Filesystem Changeset

Each layer has an archive of the files which have been added, changed, or deleted relative to its parent layer. Using a layer-based or union filesystem such as AUFS, or by computing the diff from filesystem snapshots, the filesystem changeset can be used to present a series of image layers as if they were one cohesive filesystem.

Layer DiffID

Layers are referenced by cryptographic hashes of their serialized representation. This is a SHA256 digest over the tar archive used to transport the layer, represented as a hexadecimal encoding of 256 bits, e.g., sha256:a9561eb1b190625c9adb5a9513e72c4dedafc1cb2d4c5236c9a6957ec7dfd5a9. Layers must be packed and unpacked reproducibly to avoid changing the layer ID, for example by using tar-split to save the tar headers. Note that the digest used as the layer ID is taken over an uncompressed version of the tar.

Layer ChainID

For convenience, it is sometimes useful to refer to a stack of layers with a single identifier. This is called a ChainID. For a single layer (or the layer at the bottom of a stack), the ChainID is equal to the layer's DiffID. Otherwise the ChainID is given by the formula: ChainID(layerN) = SHA256hex(ChainID(layerN-1) + " " + DiffID(layerN)).

ImageID

Each image's ID is given by the SHA256 hash of its configuration JSON. It is represented as a hexadecimal encoding of 256 bits, e.g., sha256:a9561eb1b190625c9adb5a9513e72c4dedafc1cb2d4c5236c9a6957ec7dfd5a9. Since the configuration JSON that gets hashed references hashes of each layer in the image, this formulation of the ImageID makes images content-addressable.

Tag

A tag serves to map a descriptive, user-given name to any single image ID. Tag values are limited to the set of characters [a-zA-Z0-9_.-], except they may not start with a . or - character. Tags are limited to 128 characters.

Repository

A collection of tags grouped under a common prefix (the name component before :). For example, in an image tagged with the name my-app:3.1.4, my-app is the Repository component of the name. A repository name is made up of slash-separated name components, optionally prefixed by a DNS hostname. The hostname must comply with standard DNS rules, but may not contain _ characters. If a hostname is present, it may optionally be followed by a port number in the format :8080. Name components may contain lowercase characters, digits, and separators. A separator is defined as a period, one or two underscores, or one or more dashes. A name component may not start or end with a separator.

Image JSON Description

Here is an example image JSON file:

{  
    "created": "2015-10-31T22:22:56.015925234Z",
    "author": "Alyssa P. Hacker &ltalyspdev@example.com&gt",
    "architecture": "amd64",
    "os": "linux",
    "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",
    },
    "rootfs": {
      "diff_ids": [
        "sha256:c6f988f4874bb0add23a778f753c65efe992244e148a1d2ec2a8b664fb66bbd1",
        "sha256:5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef"
      ],
      "type": "layers"
    },
    "history": [
      {
        "created": "2015-10-31T22:22:54.690851953Z",
        "created_by": "/bin/sh -c #(nop) ADD file:a3bc1e842b69636f9df5256c49c5374fb4eef1e281fe3f282c65fb853ee171c5 in /"
      },
      {
        "created": "2015-10-31T22:22:55.613815829Z",
        "created_by": "/bin/sh -c #(nop) CMD [\"sh\"]",
        "empty_layer": true
      }
    ]
}

Note that image JSON files produced by Docker don't contain formatting whitespace. It has been added to this example for clarity.

Image JSON Field Descriptions

created string

ISO-8601 formatted combined date and time at which the image was created.

author string

Gives the name and/or email address of the person or entity which created and is responsible for maintaining the image.

architecture string

The CPU architecture which the binaries in this image are built to run on. Possible values include:

• 386
• amd64
• arm

More values may be supported in the future and any of these may or may not be supported by a given container runtime implementation.

os string

The name of the operating system which the image is built to run on. Possible values include:

• darwin
• freebsd
• linux

More values may be supported in the future and any of these may or may not be supported by a given container runtime implementation.

config struct

The execution parameters which should be used as a base when running a container using the image. This field can be null, in which case any execution parameters should be specified at creation of the container.

    <h4>Container RunConfig Field Descriptions</h4>

    <dl>
        <dt>
            User <code>string</code>
        </dt>
        <dd>
            <p>The username or UID which the process in the container should
            run as. This acts as a default value to use when the value is
            not specified when creating a container.</p>

            <p>All of the following are valid:</p>

            <ul>
                <li><code>user</code></li>
                <li><code>uid</code></li>
                <li><code>user:group</code></li>
                <li><code>uid:gid</code></li>
                <li><code>uid:group</code></li>
                <li><code>user:gid</code></li>
            </ul>

            <p>If <code>group</code>/<code>gid</code> is not specified, the
            default group and supplementary groups of the given
            <code>user</code>/<code>uid</code> in <code>/etc/passwd</code>
            from the container are applied.</p>
        </dd>
        <dt>
            Memory <code>integer</code>
        </dt>
        <dd>
            Memory limit (in bytes). This acts as a default value to use
            when the value is not specified when creating a container.
        </dd>
        <dt>
            MemorySwap <code>integer</code>
        </dt>
        <dd>
            Total memory usage (memory + swap); set to <code>-1</code> to
            disable swap. This acts as a default value to use when the
            value is not specified when creating a container.
        </dd>
        <dt>
            CpuShares <code>integer</code>
        </dt>
        <dd>
            CPU shares (relative weight vs. other containers). This acts as
            a default value to use when the value is not specified when
            creating a container.
        </dd>
        <dt>
            ExposedPorts <code>struct</code>
        </dt>
        <dd>
            A set of ports to expose from a container running this image.
            This JSON structure value is unusual because it is a direct
            JSON serialization of the Go type
            <code>map[string]struct{}</code> and is represented in JSON as
            an object mapping its keys to an empty object. Here is an
            example:

{
    "8080": {},
    "53/udp": {},
    "2356/tcp": {}
}

            Its keys can be in the format of:
            <ul>
                <li>
                    <code>"port/tcp"</code>
                </li>
                <li>
                    <code>"port/udp"</code>
                </li>
                <li>
                    <code>"port"</code>
                </li>
            </ul>
            with the default protocol being <code>"tcp"</code> if not
            specified.

            These values act as defaults and are merged with any specified
            when creating a container.
        </dd>
        <dt>
            Env <code>array of strings</code>
        </dt>
        <dd>
            Entries are in the format of <code>VARNAME="var value"</code>.
            These values act as defaults and are merged with any specified
            when creating a container.
        </dd>
        <dt>
            Entrypoint <code>array of strings</code>
        </dt>
        <dd>
            A list of arguments to use as the command to execute when the
            container starts. This value acts as a  default and is replaced
            by an entrypoint specified when creating a container.
        </dd>
        <dt>
            Cmd <code>array of strings</code>
        </dt>
        <dd>
            Default arguments to the entry point of the container. These
            values act as defaults and are replaced with any specified when
            creating a container. If an <code>Entrypoint</code> value is
            not specified, then the first entry of the <code>Cmd</code>
            array should be interpreted as the executable to run.
        </dd>
        <dt>
            Healthcheck <code>struct</code>
        </dt>
        <dd>
            A test to perform to determine whether the container is healthy.
            Here is an example:

{
  "Test": [
      "CMD-SHELL",
      "/usr/bin/check-health localhost"
  ],
  "Interval": 30000000000,
  "Timeout": 10000000000,
  "Retries": 3
}

            The object has the following fields.
            <dl>
                <dt>
                    Test <code>array of strings</code>
                </dt>
                <dd>
                    The test to perform to check that the container is healthy.
                    The options are:
                    <ul>
                        <li><code>[]</code> : inherit healthcheck from base image</li>
                        <li><code>["NONE"]</code> : disable healthcheck</li>
                        <li><code>["CMD", arg1, arg2, ...]</code> : exec arguments directly</li>
                        <li><code>["CMD-SHELL", command]</code> : run command with system's default shell</li>
                    </ul>

                    The test command should exit with a status of 0 if the container is healthy,
                    or with 1 if it is unhealthy.
                </dd>
                <dt>
                    Interval <code>integer</code>
                </dt>
                <dd>
                    Number of nanoseconds to wait between probe attempts.
                </dd>
                <dt>
                    Timeout <code>integer</code>
                </dt>
                <dd>
                    Number of nanoseconds to wait before considering the check to have hung.
                </dd>
                <dt>
                    Retries <code>integer</code>
                <dt>
                <dd>
                    The number of consecutive failures needed to consider a container as unhealthy.
                </dd>
            </dl>

            In each case, the field can be omitted to indicate that the
            value should be inherited from the base layer.

            These values act as defaults and are merged with any specified
            when creating a container.
        </dd>
        <dt>
            Volumes <code>struct</code>
        </dt>
        <dd>
            A set of directories which should be created as data volumes in
            a container running this image. This JSON structure value is
            unusual because it is a direct JSON serialization of the Go
            type <code>map[string]struct{}</code> and is represented in
            JSON as an object mapping its keys to an empty object. Here is
            an example:

{
    "/var/my-app-data/": {},
    "/etc/some-config.d/": {},
}

        </dd>
        <dt>
            WorkingDir <code>string</code>
        </dt>
        <dd>
            Sets the current working directory of the entry point process
            in the container. This value acts as a default and is replaced
            by a working directory specified when creating a container.
        </dd>
    </dl>
</dd>
<dt>
    rootfs <code>struct</code>
</dt>
<dd>
    The rootfs key references the layer content addresses used by the
    image. This makes the image config hash depend on the filesystem hash.
    rootfs has two subkeys:

    <ul>
      <li>
        <code>type</code> is usually set to <code>layers</code>.
      </li>
      <li>
        <code>diff_ids</code> is an array of layer content hashes (<code>DiffIDs</code>), in order from bottom-most to top-most.
      </li>
    </ul>


    Here is an example rootfs section:

"rootfs": {
  "diff_ids": [
    "sha256:c6f988f4874bb0add23a778f753c65efe992244e148a1d2ec2a8b664fb66bbd1",
    "sha256:5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef",
    "sha256:13f53e08df5a220ab6d13c58b2bf83a59cbdc2e04d0a3f041ddf4b0ba4112d49"
  ],
  "type": "layers"
}

</dd>
<dt>
    history <code>struct</code>
</dt>
<dd>
    <code>history</code> is an array of objects describing the history of
    each layer. The array is ordered from bottom-most layer to top-most
    layer. The object has the following fields.

    <ul>
      <li>
        <code>created</code>: Creation time, expressed as a ISO-8601 formatted
        combined date and time
      </li>
      <li>
        <code>author</code>: The author of the build point
      </li>
      <li>
        <code>created_by</code>: The command which created the layer
      </li>
      <li>
        <code>comment</code>: A custom message set when creating the layer
      </li>
      <li>
        <code>empty_layer</code>: This field is used to mark if the history
        item created a filesystem diff. It is set to true if this history
        item doesn't correspond to an actual layer in the rootfs section
        (for example, a command like ENV which results in no change to the
        filesystem).
      </li>
    </ul>

Here is an example history section:

"history": [
  {
    "created": "2015-10-31T22:22:54.690851953Z",
    "created_by": "/bin/sh -c #(nop) ADD file:a3bc1e842b69636f9df5256c49c5374fb4eef1e281fe3f282c65fb853ee171c5 in /"
  },
  {
    "created": "2015-10-31T22:22:55.613815829Z",
    "created_by": "/bin/sh -c #(nop) CMD [\"sh\"]",
    "empty_layer": true
  }
]

</dd>

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.

Creating an Image Filesystem Changeset

An example of creating an Image Filesystem Changeset follows.

An image root filesystem is first created as an empty directory. Here is the initial empty directory structure for the a changeset using the randomly-generated directory name c3167915dc9d (actual layer DiffIDs are generated based on the content).

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

To make changes to the filesystem of this container image, create a new directory, 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 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.

Combined Image JSON + Filesystem Changeset Format

There is also a format for a single archive which contains complete information about an image, including:

• repository names/tags
• image configuration JSON file
• all tar archives of each layer filesystem changesets

For example, here's what the full archive of library/busybox is (displayed in tree format):

.
├── 47bcc53f74dc94b1920f0b34f6036096526296767650f223433fe65c35f149eb.json
├── 5f29f704785248ddb9d06b90a11b5ea36c534865e9035e4022bb2e71d4ecbb9a
│   ├── VERSION
│   ├── json
│   └── layer.tar
├── a65da33792c5187473faa80fa3e1b975acba06712852d1dea860692ccddf3198
│   ├── VERSION
│   ├── json
│   └── layer.tar
├── manifest.json
└── repositories

There is a directory for each layer in the image. Each directory is named with a 64 character hex name that is deterministically generated from the layer information. These names are not necessarily layer DiffIDs or ChainIDs. Each of these directories contains 3 files:

• VERSION - The schema version of the json file
• json - The legacy JSON metadata for an image layer. In this version of the image specification, layers don't have JSON metadata, but in version 1, they did. A file is created for each layer in the v1 format for backward compatibility.
• layer.tar - The Tar archive of the filesystem changeset for an image layer.

Note that this directory layout is only important for backward compatibility. Current implementations use the paths specified in manifest.json.

The content of the VERSION files is simply the semantic version of the JSON metadata schema:

1.0

The repositories file is another JSON file which describes names/tags:

{  
    "busybox":{  
        "latest":"5f29f704785248ddb9d06b90a11b5ea36c534865e9035e4022bb2e71d4ecbb9a"
    }
}

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. This file is only used for backwards compatibility. Current implementations use the manifest.json file instead.

The manifest.json file provides the image JSON for the top-level image, and optionally for parent images that this image was derived from. It consists of an array of metadata entries:

[
  {
    "Config": "47bcc53f74dc94b1920f0b34f6036096526296767650f223433fe65c35f149eb.json",
    "RepoTags": ["busybox:latest"],
    "Layers": [
      "a65da33792c5187473faa80fa3e1b975acba06712852d1dea860692ccddf3198/layer.tar",
      "5f29f704785248ddb9d06b90a11b5ea36c534865e9035e4022bb2e71d4ecbb9a/layer.tar"
    ]
  }
]

There is an entry in the array for each image.

The Config field references another file in the tar which includes the image JSON for this image.

The RepoTags field lists references pointing to this image.

The Layers field points to the filesystem changeset tars.

An optional Parent field references the imageID of the parent image. This parent must be part of the same manifest.json file.

This file shouldn't be confused with the distribution manifest, used to push and pull images.

Generally, implementations that support this version of the spec will use the manifest.json file if available, and older implementations will use the legacy */json files and repositories.