Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document Healthcheck in image spec #25750

Merged
merged 1 commit into from
Aug 25, 2016
Merged

Document Healthcheck in image spec #25750

merged 1 commit into from
Aug 25, 2016

Conversation

talex5
Copy link
Contributor

@talex5 talex5 commented Aug 16, 2016

- 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
Copy link
Member

vdemeester commented Aug 16, 2016

LGTM 👼
/cc @thaJeztah @icecrime

@jbayer
Copy link

jbayer commented Aug 16, 2016

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
Copy link
Member

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

@talex5 talex5 force-pushed the spec branch 2 times, most recently from 3897ec4 to e0b1bf2 Compare August 16, 2016 16:14
@talex5
Copy link
Contributor Author

talex5 commented Aug 16, 2016

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

@jbayer
Copy link

jbayer commented Aug 16, 2016

thank you! that looks great and aligns with semver.

@stevvooe
Copy link
Contributor

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

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

@talex5
Copy link
Contributor Author

talex5 commented Aug 17, 2016

@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
Copy link
Member

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
Copy link
Contributor

LGTM

<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>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
Copy link
Contributor Author

talex5 commented Aug 18, 2016

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

@thaJeztah
Copy link
Member

@talex5 thanks! can you squash your commits? 😇

Signed-off-by: Thomas Leonard <thomas.leonard@docker.com>
@SvenDowideit
Copy link
Contributor

LGTM

@vdemeester
Copy link
Member

LGTM 🐸

@icecrime
Copy link
Contributor

Thanks!

@icecrime icecrime merged commit 46cb1f2 into moby:master Aug 25, 2016
sfsmithcha pushed a commit to sfsmithcha/docker that referenced this pull request Aug 26, 2016
Document Healthcheck in image spec
(cherry picked from commit 46cb1f2)

Signed-off-by: Charles Smith <charles.smith@docker.com>
@stevvooe
Copy link
Contributor

@talex5 Thanks for taking care of this!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

9 participants