Document Healthcheck in image spec#25750
Conversation
|
LGTM 👼 |
|
updating the |
|
Yes, I think the plan was to bump to 1.2, but ping @stevvooe to have a look |
3897ec4 to
e0b1bf2
Compare
|
OK, I've made a new v1.2.0 version instead now. |
|
thank you! that looks great and aligns with semver. |
|
@talex5 Is there diff of this so we can actually review it? Wish we used a changelog, rather than copying document each time... |
|
@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. |
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> |
|
LGTM |
image/spec/v1.2.md
Outdated
There was a problem hiding this comment.
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", ...]
|
@thaJeztah thanks - I've updated it as you suggested |
|
@talex5 thanks! can you squash your commits? 😇 |
Signed-off-by: Thomas Leonard <[email protected]>
|
LGTM |
|
LGTM 🐸 |
|
Thanks! |
Document Healthcheck in image spec (cherry picked from commit 46cb1f2) Signed-off-by: Charles Smith <[email protected]>
|
@talex5 Thanks for taking care of this! |
- 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 [email protected]