Merge pull request #25750 from talex5/spec

Document Healthcheck in image spec

image/spec/v1.2.md

@@ -0,0 +1,696 @@
+# 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:
+
+<dl>
+    <dt>
+        Layer
+    </dt>
+    <dd>
+        Images are composed of <i>layers</i>. 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.
+    </dd>
+    <dt>
+        Image JSON
+    </dt>
+    <dd>
+        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.
+    </dd>
+    <dt>
+        Image Filesystem Changeset
+    </dt>
+    <dd>
+        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.
+    </dd>
+    <dt>
+        Layer DiffID
+    </dt>
+    <dd>
+        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.,
+        <code>sha256:a9561eb1b190625c9adb5a9513e72c4dedafc1cb2d4c5236c9a6957ec7dfd5a9</code>.
+        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.
+    </dd>
+    <dt>
+        Layer ChainID
+    </dt>
+    <dd>
+        For convenience, it is sometimes useful to refer to a stack of layers
+        with a single identifier. This is called a <code>ChainID</code>. For a
+        single layer (or the layer at the bottom of a stack), the
+        <code>ChainID</code> is equal to the layer's <code>DiffID</code>.
+        Otherwise the <code>ChainID</code> is given by the formula:
+        <code>ChainID(layerN) = SHA256hex(ChainID(layerN-1) + " " + DiffID(layerN))</code>.
+    </dd>
+    <dt>
+        ImageID <a name="id_desc"></a>
+    </dt>
+    <dd>
+        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.,
+        <code>sha256:a9561eb1b190625c9adb5a9513e72c4dedafc1cb2d4c5236c9a6957ec7dfd5a9</code>.
+        Since the configuration JSON that gets hashed references hashes of each
+        layer in the image, this formulation of the ImageID makes images
+        content-addresable.
+    </dd>
+    <dt>
+        Tag
+    </dt>
+    <dd>
+        A tag serves to map a descriptive, user-given name to any single image
+        ID. Tag values are limited to the set of characters
+        <code>[a-zA-Z0-9_.-]</code>, except they may not start with a <code>.</code>
+        or <code>-</code> character. Tags are limited to 127 characters.
+    </dd>
+    <dt>
+        Repository
+    </dt>
+    <dd>
+        A collection of tags grouped under a common prefix (the name component
+        before <code>:</code>). For example, in an image tagged with the name
+        <code>my-app:3.1.4</code>, <code>my-app</code> is the <i>Repository</i>
+        component of the name. A repository name is made up of slash-separated
+        name components, optionally prefixed by a DNS hostname. The hostname
+        must follow comply with standard DNS rules, but may not contain
+        <code>_</code> characters. If a hostname is present, it may optionally
+        be followed by a port number in the format <code>:8080</code>.
+        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.
+    </dd>
+</dl>
+
+## 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
+
+<dl>
+    <dt>
+        created <code>string</code>
+    </dt>
+    <dd>
+        ISO-8601 formatted combined date and time at which the image was
+        created.
+    </dd>
+    <dt>
+        author <code>string</code>
+    </dt>
+    <dd>
+        Gives the name and/or email address of the person or entity which
+        created and is responsible for maintaining the image.
+    </dd>
+    <dt>
+        architecture <code>string</code>
+    </dt>
+    <dd>
+        The CPU architecture which the binaries in this image are built to run
+        on. Possible values include:
+        <ul>
+            <li>386</li>
+            <li>amd64</li>
+            <li>arm</li>
+        </ul>
+        More values may be supported in the future and any of these may or may
+        not be supported by a given container runtime implementation.
+    </dd>
+    <dt>
+        os <code>string</code>
+    </dt>
+    <dd>
+        The name of the operating system which the image is built to run on.
+        Possible values include:
+        <ul>
+            <li>darwin</li>
+            <li>freebsd</li>
+            <li>linux</li>
+        </ul>
+        More values may be supported in the future and any of these may or may
+        not be supported by a given container runtime implementation.
+    </dd>
+    <dt>
+        config <code>struct</code>
+    </dt>
+    <dd>
+        The execution parameters which should be used as a base when running a
+        container using the image. This field can be <code>null</code>, 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:
+
+<pre>{
+    "8080": {},
+    "53/udp": {},
+    "2356/tcp": {}
+}</pre>
+
+                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:
+<pre>{
+  "Test": [
+      "CMD-SHELL",
+      "/usr/bin/check-health localhost"
+  ],
+  "Interval": 30000000000,
+  "Timeout": 10000000000,
+  "Retries": 3
+}</pre>
+                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:
+<pre>{
+    "/var/my-app-data/": {},
+    "/etc/some-config.d/": {},
+}</pre>
+            </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:
+
+<pre>"rootfs": {
+  "diff_ids": [
+    "sha256:c6f988f4874bb0add23a778f753c65efe992244e148a1d2ec2a8b664fb66bbd1",
+    "sha256:5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef",
+    "sha256:13f53e08df5a220ab6d13c58b2bf83a59cbdc2e04d0a3f041ddf4b0ba4112d49"
+  ],
+  "type": "layers"
+}</pre>
+    </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:
+
+<pre>"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
+  }
+]</pre>
+    </dd>
+</dl>
+
+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](#id_desc)).
+
+```
+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](v1.md), 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`.