mirror of
https://github.com/moby/moby.git
synced 2022-11-09 12:21:53 -05:00
b6c7becbfe
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>
72 lines
3 KiB
Go
72 lines
3 KiB
Go
package container
|
|
|
|
import (
|
|
"io"
|
|
"time"
|
|
|
|
"golang.org/x/net/context"
|
|
|
|
"github.com/docker/docker/api/types/backend"
|
|
"github.com/docker/docker/pkg/archive"
|
|
"github.com/docker/engine-api/types"
|
|
"github.com/docker/engine-api/types/container"
|
|
)
|
|
|
|
// execBackend includes functions to implement to provide exec functionality.
|
|
type execBackend interface {
|
|
ContainerExecCreate(name string, config *types.ExecConfig) (string, error)
|
|
ContainerExecInspect(id string) (*backend.ExecInspect, error)
|
|
ContainerExecResize(name string, height, width int) error
|
|
ContainerExecStart(ctx context.Context, name string, stdin io.ReadCloser, stdout io.Writer, stderr io.Writer) error
|
|
ExecExists(name string) (bool, error)
|
|
}
|
|
|
|
// copyBackend includes functions to implement to provide container copy functionality.
|
|
type copyBackend interface {
|
|
ContainerArchivePath(name string, path string) (content io.ReadCloser, stat *types.ContainerPathStat, err error)
|
|
ContainerCopy(name string, res string) (io.ReadCloser, error)
|
|
ContainerExport(name string, out io.Writer) error
|
|
ContainerExtractToDir(name, path string, noOverwriteDirNonDir bool, content io.Reader) error
|
|
ContainerStatPath(name string, path string) (stat *types.ContainerPathStat, err error)
|
|
}
|
|
|
|
// stateBackend includes functions to implement to provide container state lifecycle functionality.
|
|
type stateBackend interface {
|
|
ContainerCreate(types.ContainerCreateConfig) (types.ContainerCreateResponse, error)
|
|
ContainerKill(name string, sig uint64) error
|
|
ContainerPause(name string) error
|
|
ContainerRename(oldName, newName string) error
|
|
ContainerResize(name string, height, width int) error
|
|
ContainerRestart(name string, seconds int) error
|
|
ContainerRm(name string, config *types.ContainerRmConfig) error
|
|
ContainerStart(name string, hostConfig *container.HostConfig) error
|
|
ContainerStop(name string, seconds int) error
|
|
ContainerUnpause(name string) error
|
|
ContainerUpdate(name string, hostConfig *container.HostConfig) ([]string, error)
|
|
ContainerWait(name string, timeout time.Duration) (int, error)
|
|
}
|
|
|
|
// monitorBackend includes functions to implement to provide containers monitoring functionality.
|
|
type monitorBackend interface {
|
|
ContainerChanges(name string) ([]archive.Change, error)
|
|
ContainerInspect(name string, size bool, version string) (interface{}, error)
|
|
ContainerLogs(ctx context.Context, name string, config *backend.ContainerLogsConfig, started chan struct{}) error
|
|
ContainerStats(ctx context.Context, name string, config *backend.ContainerStatsConfig) error
|
|
ContainerTop(name string, psArgs string) (*types.ContainerProcessList, error)
|
|
|
|
Containers(config *types.ContainerListOptions) ([]*types.Container, error)
|
|
}
|
|
|
|
// attachBackend includes function to implement to provide container attaching functionality.
|
|
type attachBackend interface {
|
|
ContainerAttach(name string, c *backend.ContainerAttachConfig) error
|
|
}
|
|
|
|
// Backend is all the methods that need to be implemented to provide container specific functionality.
|
|
type Backend interface {
|
|
execBackend
|
|
copyBackend
|
|
stateBackend
|
|
monitorBackend
|
|
attachBackend
|
|
}
|