Problem statement

Docker currently doesn't provide any built-in way to determine if a container is "alive" in the sense that the service it provides is up and running. This is useful in many scenarios, for example:

• Sequencing dependent containers (e.g., Is there a way to delay container startup to support dependant services with a longer startup time docker/compose#374)
• Taking informed load-balancing decisions
• Restarting the container on an application-specific criteria

This issue cover the support for "alive probes" at the Engine level.

Proposal

Every container would support one optional container-specific probe to determine whether a service is alive. This would translate in docker UX through several new command line options for the run sub-command (naming to be discussed):

A container is considered alive when the probe returns 0 for a file:// based probe, or a status code in the 200-399 range for an http[s]:// based probe.

Examples:

docker run -d \
           --probe="file:///some/script.sh" \
           --probe-interval=120 myimage

Open questions

Implementation

• Should it be a new value for the container state, or should it be a new field in the container definition?
• Should probe failure be reported in the events API?

Restart policies

• Should we back restart policies on the probe result?
• Can we implicitly alter the behavior of --restart=always and --restart=on-failure when a --probe is specified? That is roughly equivalent to assuming that the restart policy was always backed by a default probe which behavior is to look for the container process being alive.

References

• Credits to @dongluochen for the initial design

Ping @crosbymichael @tonistiigi @mgoelzer @aluzzardi @ehazlett