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>
|
||
|---|---|---|
| .. | ||
| fixtures | ||
| benchmark_test.go | ||
| check_test.go | ||
| daemon.go | ||
| docker_api_attach_test.go | ||
| docker_api_auth_test.go | ||
| docker_api_build_test.go | ||
| docker_api_containers_test.go | ||
| docker_api_create_test.go | ||
| docker_api_events_test.go | ||
| docker_api_exec_resize_test.go | ||
| docker_api_exec_test.go | ||
| docker_api_images_test.go | ||
| docker_api_info_test.go | ||
| docker_api_inspect_test.go | ||
| docker_api_inspect_unix_test.go | ||
| docker_api_logs_test.go | ||
| docker_api_network_test.go | ||
| docker_api_resize_test.go | ||
| docker_api_stats_test.go | ||
| docker_api_stats_unix_test.go | ||
| docker_api_test.go | ||
| docker_api_update_unix_test.go | ||
| docker_api_version_test.go | ||
| docker_api_volumes_test.go | ||
| docker_cli_attach_test.go | ||
| docker_cli_attach_unix_test.go | ||
| docker_cli_authz_unix_test.go | ||
| docker_cli_build_test.go | ||
| docker_cli_build_unix_test.go | ||
| docker_cli_by_digest_test.go | ||
| docker_cli_commit_test.go | ||
| docker_cli_config_test.go | ||
| docker_cli_cp_from_container_test.go | ||
| docker_cli_cp_test.go | ||
| docker_cli_cp_to_container_test.go | ||
| docker_cli_cp_to_container_unix_test.go | ||
| docker_cli_cp_utils.go | ||
| docker_cli_create_test.go | ||
| docker_cli_daemon_experimental_test.go | ||
| docker_cli_daemon_test.go | ||
| docker_cli_diff_test.go | ||
| docker_cli_events_test.go | ||
| docker_cli_events_unix_test.go | ||
| docker_cli_exec_test.go | ||
| docker_cli_exec_unix_test.go | ||
| docker_cli_experimental_test.go | ||
| docker_cli_export_import_test.go | ||
| docker_cli_external_graphdriver_unix_test.go | ||
| docker_cli_external_volume_driver_unix_test.go | ||
| docker_cli_health_test.go | ||
| docker_cli_help_test.go | ||
| docker_cli_history_test.go | ||
| docker_cli_images_test.go | ||
| docker_cli_import_test.go | ||
| docker_cli_info_test.go | ||
| docker_cli_inspect_experimental_test.go | ||
| docker_cli_inspect_test.go | ||
| docker_cli_kill_test.go | ||
| docker_cli_links_test.go | ||
| docker_cli_links_unix_test.go | ||
| docker_cli_login_test.go | ||
| docker_cli_logout_test.go | ||
| docker_cli_logs_bench_test.go | ||
| docker_cli_logs_test.go | ||
| docker_cli_nat_test.go | ||
| docker_cli_netmode_test.go | ||
| docker_cli_network_unix_test.go | ||
| docker_cli_oom_killed_test.go | ||
| docker_cli_pause_test.go | ||
| docker_cli_port_test.go | ||
| docker_cli_proxy_test.go | ||
| docker_cli_ps_test.go | ||
| docker_cli_pull_local_test.go | ||
| docker_cli_pull_test.go | ||
| docker_cli_pull_trusted_test.go | ||
| docker_cli_push_test.go | ||
| docker_cli_registry_user_agent_test.go | ||
| docker_cli_rename_test.go | ||
| docker_cli_restart_test.go | ||
| docker_cli_rm_test.go | ||
| docker_cli_rmi_test.go | ||
| docker_cli_run_test.go | ||
| docker_cli_run_unix_test.go | ||
| docker_cli_save_load_test.go | ||
| docker_cli_save_load_unix_test.go | ||
| docker_cli_search_test.go | ||
| docker_cli_sni_test.go | ||
| docker_cli_start_test.go | ||
| docker_cli_stats_test.go | ||
| docker_cli_stop_test.go | ||
| docker_cli_tag_test.go | ||
| docker_cli_top_test.go | ||
| docker_cli_update_test.go | ||
| docker_cli_update_unix_test.go | ||
| docker_cli_userns_test.go | ||
| docker_cli_v2_only_test.go | ||
| docker_cli_version_test.go | ||
| docker_cli_volume_test.go | ||
| docker_cli_wait_test.go | ||
| docker_deprecated_api_v124_test.go | ||
| docker_deprecated_api_v124_unix_test.go | ||
| docker_experimental_network_test.go | ||
| docker_hub_pull_suite_test.go | ||
| docker_test_vars.go | ||
| docker_utils.go | ||
| events_utils.go | ||
| npipe.go | ||
| npipe_windows.go | ||
| registry.go | ||
| registry_mock.go | ||
| requirements.go | ||
| requirements_unix.go | ||
| test_vars_exec.go | ||
| test_vars_noexec.go | ||
| test_vars_noseccomp.go | ||
| test_vars_seccomp.go | ||
| test_vars_unix.go | ||
| test_vars_windows.go | ||
| trust_server.go | ||
| utils.go | ||