Document Healthcheck in image spec

[talex5]

- What I did

Added description of the JSON Healthcheck configuration object to the image spec, as requested.

- Description for the changelog

Add Healthcheck to image spec documentation.

Fixes #25260.

Signed-off-by: Thomas Leonard thomas.leonard@docker.com

[vdemeester]

LGTM 👼
/cc @thaJeztah @icecrime

[jbayer]

updating the v1.1.md file as-is does not seem to be the right approach since this capability was added after v1.1.md was originally specified. if using semver as @stevvooe and i discussed in the original issue #25260 then i would expect a new file for v1.2.md or v1.1.1.md or similar. if the docker image specification version is not stable and new features final on a particular version (that means adding new features introduces a new version number), then it makes it very difficult on the ecosystem to say whether they can support a docker particular image.

[thaJeztah]

Yes, I think the plan was to bump to 1.2, but ping @stevvooe to have a look

[talex5]

OK, I've made a new v1.2.0 version instead now.

[jbayer]

thank you! that looks great and aligns with semver.

[stevvooe]

@talex5 Is there diff of this so we can actually review it?

Wish we used a changelog, rather than copying document each time...

[talex5]

@stevvooe there's no diff in the GitHub view since moving it to a new file, but you can diff the 1.1 and 1.2 files from the command-line.

[thaJeztah]

diff --git a/image/spec/v1.2.md b/image/spec/v1.2.md
index 63e97de..08b0025 100644
--- a/image/spec/v1.2.md
+++ b/image/spec/v1.2.md
@@ -1,4 +1,4 @@
-# Docker Image Specification v1.1.0
+# 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
@@ -6,7 +6,7 @@ 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.10.
+This version of the image specification was adopted starting in Docker 1.12.

 ## Terminology

@@ -336,6 +336,65 @@ whitespace. It has been added to this example for clarity.
                 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", args...}</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>
+                        Nanoseconds to wait between probe attempts.
+                    </dd>
+                    <dt>
+                        Timeout <code>integer</code>
+                    </dt>
+                    <dd>
+                        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>

[stevvooe]

LGTM

[thaJeztah]

These should use square brackets, not curly ones; perhaps be clearer about args.. to illustrate that each "arg" is a separate string in the array (if I'm correct), same with command (if it takes args) - also if I'm correct;

[]
["NONE"]
["CMD", "arg1", "arg2", ...]
["CMD-SHELL", "command", "arg1", ...]

[talex5]

@thaJeztah thanks - I've updated it as you suggested

[thaJeztah]

@talex5 thanks! can you squash your commits? 😇

[SvenDowideit]

LGTM

[vdemeester]

LGTM 🐸

[icecrime]

Thanks!

[stevvooe]

@talex5 Thanks for taking care of this!