This PR adds support for user-defined health-check probes for Docker
containers. It adds a `HEALTHCHECK` instruction to the Dockerfile syntax plus
some corresponding "docker run" options. It can be used with a restart policy
to automatically restart a container if the check fails.
The `HEALTHCHECK` instruction has two forms:
* `HEALTHCHECK [OPTIONS] CMD command` (check container health by running a command inside the container)
* `HEALTHCHECK NONE` (disable any healthcheck inherited from the base image)
The `HEALTHCHECK` instruction tells Docker how to test a container to check that
it is still working. This can detect cases such as a web server that is stuck in
an infinite loop and unable to handle new connections, even though the server
process is still running.
When a container has a healthcheck specified, it has a _health status_ in
addition to its normal status. This status is initially `starting`. Whenever a
health check passes, it becomes `healthy` (whatever state it was previously in).
After a certain number of consecutive failures, it becomes `unhealthy`.
The options that can appear before `CMD` are:
* `--interval=DURATION` (default: `30s`)
* `--timeout=DURATION` (default: `30s`)
* `--retries=N` (default: `1`)
The health check will first run **interval** seconds after the container is
started, and then again **interval** seconds after each previous check completes.
If a single run of the check takes longer than **timeout** seconds then the check
is considered to have failed.
It takes **retries** consecutive failures of the health check for the container
to be considered `unhealthy`.
There can only be one `HEALTHCHECK` instruction in a Dockerfile. If you list
more than one then only the last `HEALTHCHECK` will take effect.
The command after the `CMD` keyword can be either a shell command (e.g. `HEALTHCHECK
CMD /bin/check-running`) or an _exec_ array (as with other Dockerfile commands;
see e.g. `ENTRYPOINT` for details).
The command's exit status indicates the health status of the container.
The possible values are:
- 0: success - the container is healthy and ready for use
- 1: unhealthy - the container is not working correctly
- 2: starting - the container is not ready for use yet, but is working correctly
If the probe returns 2 ("starting") when the container has already moved out of the
"starting" state then it is treated as "unhealthy" instead.
For example, to check every five minutes or so that a web-server is able to
serve the site's main page within three seconds:
HEALTHCHECK --interval=5m --timeout=3s \
CMD curl -f http://localhost/ || exit 1
To help debug failing probes, any output text (UTF-8 encoded) that the command writes
on stdout or stderr will be stored in the health status and can be queried with
`docker inspect`. Such output should be kept short (only the first 4096 bytes
are stored currently).
When the health status of a container changes, a `health_status` event is
generated with the new status. The health status is also displayed in the
`docker ps` output.
Signed-off-by: Thomas Leonard <thomas.leonard@docker.com>
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
Upstream-commit: b6c7becbfe1d76b1250f6d8e991e645e13808a9c
Component: engine
135 lines
3.7 KiB
Go
135 lines
3.7 KiB
Go
package container
|
|
|
|
import (
|
|
"encoding/json"
|
|
"fmt"
|
|
"io"
|
|
"net/http"
|
|
"strconv"
|
|
|
|
"github.com/Sirupsen/logrus"
|
|
"github.com/docker/docker/api/server/httputils"
|
|
"github.com/docker/docker/pkg/stdcopy"
|
|
"github.com/docker/engine-api/types"
|
|
"github.com/docker/engine-api/types/versions"
|
|
"golang.org/x/net/context"
|
|
)
|
|
|
|
func (s *containerRouter) getExecByID(ctx context.Context, w http.ResponseWriter, r *http.Request, vars map[string]string) error {
|
|
eConfig, err := s.backend.ContainerExecInspect(vars["id"])
|
|
if err != nil {
|
|
return err
|
|
}
|
|
|
|
return httputils.WriteJSON(w, http.StatusOK, eConfig)
|
|
}
|
|
|
|
func (s *containerRouter) postContainerExecCreate(ctx context.Context, w http.ResponseWriter, r *http.Request, vars map[string]string) error {
|
|
if err := httputils.ParseForm(r); err != nil {
|
|
return err
|
|
}
|
|
if err := httputils.CheckForJSON(r); err != nil {
|
|
return err
|
|
}
|
|
name := vars["name"]
|
|
|
|
execConfig := &types.ExecConfig{}
|
|
if err := json.NewDecoder(r.Body).Decode(execConfig); err != nil {
|
|
return err
|
|
}
|
|
|
|
if len(execConfig.Cmd) == 0 {
|
|
return fmt.Errorf("No exec command specified")
|
|
}
|
|
|
|
// Register an instance of Exec in container.
|
|
id, err := s.backend.ContainerExecCreate(name, execConfig)
|
|
if err != nil {
|
|
logrus.Errorf("Error setting up exec command in container %s: %v", name, err)
|
|
return err
|
|
}
|
|
|
|
return httputils.WriteJSON(w, http.StatusCreated, &types.ContainerExecCreateResponse{
|
|
ID: id,
|
|
})
|
|
}
|
|
|
|
// TODO(vishh): Refactor the code to avoid having to specify stream config as part of both create and start.
|
|
func (s *containerRouter) postContainerExecStart(ctx context.Context, w http.ResponseWriter, r *http.Request, vars map[string]string) error {
|
|
if err := httputils.ParseForm(r); err != nil {
|
|
return err
|
|
}
|
|
|
|
version := httputils.VersionFromContext(ctx)
|
|
if versions.GreaterThan(version, "1.21") {
|
|
if err := httputils.CheckForJSON(r); err != nil {
|
|
return err
|
|
}
|
|
}
|
|
|
|
var (
|
|
execName = vars["name"]
|
|
stdin, inStream io.ReadCloser
|
|
stdout, stderr, outStream io.Writer
|
|
)
|
|
|
|
execStartCheck := &types.ExecStartCheck{}
|
|
if err := json.NewDecoder(r.Body).Decode(execStartCheck); err != nil {
|
|
return err
|
|
}
|
|
|
|
if exists, err := s.backend.ExecExists(execName); !exists {
|
|
return err
|
|
}
|
|
|
|
if !execStartCheck.Detach {
|
|
var err error
|
|
// Setting up the streaming http interface.
|
|
inStream, outStream, err = httputils.HijackConnection(w)
|
|
if err != nil {
|
|
return err
|
|
}
|
|
defer httputils.CloseStreams(inStream, outStream)
|
|
|
|
if _, ok := r.Header["Upgrade"]; ok {
|
|
fmt.Fprintf(outStream, "HTTP/1.1 101 UPGRADED\r\nContent-Type: application/vnd.docker.raw-stream\r\nConnection: Upgrade\r\nUpgrade: tcp\r\n\r\n")
|
|
} else {
|
|
fmt.Fprintf(outStream, "HTTP/1.1 200 OK\r\nContent-Type: application/vnd.docker.raw-stream\r\n\r\n")
|
|
}
|
|
|
|
stdin = inStream
|
|
stdout = outStream
|
|
if !execStartCheck.Tty {
|
|
stderr = stdcopy.NewStdWriter(outStream, stdcopy.Stderr)
|
|
stdout = stdcopy.NewStdWriter(outStream, stdcopy.Stdout)
|
|
}
|
|
}
|
|
|
|
// Now run the user process in container.
|
|
// Maybe we should we pass ctx here if we're not detaching?
|
|
if err := s.backend.ContainerExecStart(context.Background(), execName, stdin, stdout, stderr); err != nil {
|
|
if execStartCheck.Detach {
|
|
return err
|
|
}
|
|
stdout.Write([]byte(err.Error() + "\r\n"))
|
|
logrus.Errorf("Error running exec in container: %v", err)
|
|
}
|
|
return nil
|
|
}
|
|
|
|
func (s *containerRouter) postContainerExecResize(ctx context.Context, w http.ResponseWriter, r *http.Request, vars map[string]string) error {
|
|
if err := httputils.ParseForm(r); err != nil {
|
|
return err
|
|
}
|
|
height, err := strconv.Atoi(r.Form.Get("h"))
|
|
if err != nil {
|
|
return err
|
|
}
|
|
width, err := strconv.Atoi(r.Form.Get("w"))
|
|
if err != nil {
|
|
return err
|
|
}
|
|
|
|
return s.backend.ContainerExecResize(vars["name"], height, width)
|
|
}
|