edit-icon download-icon

Health check

Last Updated: Feb 12, 2018

Template version

Compose V1/V2 Compose V3
The aliyun.probe label. healthcheck in Compose. This is a native function of Docker Engine.

Compose V1/V2

Set the service health check.

  • Check the health by using URLs. HTTP and TCP protocols are supported.
  • Check the health by using shell scripts.

The health check is initiated from the container host. At regular intervals (two seconds by default), a request is sent to the container or the shell script commands are run on the container.

The health check is successful if the following criteria are met:

  • The HTTP request returns the code 2XX/3XX.
  • The TCP port can establish a link.
  • The shell scripts return the value 0.

Descriptions of the fields used for check:

  • aliyun.probe.url: The URL requested by HTTP and TCP. No need to enter your own domain name or IP address. Add the word container. The URL is used for the health check after being resolved into the corresponding IP address of the container. The service passes the health check when 2XX or 3XX is returned.

    • For example, the container provides the HTTP service by using the port 8080 and provides /ping as the URL for the health check. The URL format for the probe is http://container:8080/ping. Container Service automatically uses HTTP GET requests to check the URL returned results. The health check is successful if 2XX or 3XX is returned.

    • For example, MySQL container monitors port 3306. The URL format for the probe is tcp://container:3306. The service checks whether the container opens the port 3306 or not. If yes, the health check is successful.

  • aliyun.probe.cmd: The shell command, /check.sh, is run during the health check. Container Service regularly runs this command in the container. If the shell scripts return the value 0, the health check is successful.

  • aliyun.probe.timeout_seconds: The timeout for health check.

  • aliyun.probe.initial_delay_seconds: The number of seconds delayed to start the health check after the container is started.

Note:

  • A service can only contain either aliyun.probe.url or aliyun.probe.cmd.
  • If both aliyun.probe.url and aliyun.probe.cmd are not contained in the service, by default, the container is healthy and other aliyun.probe.xxx labels are ignored.

Orchestration example:

Use URL to check whether or not the container is healthy.

  1. os:
  2. image: my_nginx
  3. labels:
  4. aliyun.probe.url: http://container/ping
  5. aliyun.probe.timeout_seconds: "10"
  6. aliyun.probe.initial_delay_seconds: "3"

Use shell scripts to check whether or not the container is healthy.

  1. os:
  2. image: my_app
  3. labels:
  4. aliyun.probe.cmd: health_check.sh
  5. aliyun.probe.initial_delay_seconds: "3"

Compose V3

Set the service health check.

The healthcheck commands include the following formats:

  • test: ["CMD", "curl", "-f", "http://localhost"]: Run the command to check whether or not the container is healthy.
  • test: ["CMD-SHELL", "curl -f http://localhost && echo 'cool, it works'"]: Run the command to check whether or not the container is healthy.
  • test: curl -f https://localhost && echo 'cool, it works': Run the command to check whether or not the container is healthy.
  • test: ["NONE"]: Disable all the health check settings in the image.
    You can also use:
    1. healthcheck:
    2. disable: true

The health check is successful if the following criteria are met:

The exit status of the command indicates the health status of the containers.

  • 0: Successful. The container is healthy and ready for use.
  • 1: Unhealthy. The container is not working correctly.
  • 2: Reserved. Do not use this exit code.

Descriptions of the fields used for check:

  • interval: The time interval between health checks. The default value is 30s.
  • timeout: The timeout for health check. The default value is 30s.
  • start-period: The number of seconds delayed to start the health check after the container is started. The default value is 0s.
  • retries: The container is considered as unhealthy after how many times of consecutive failures of health check. The default value is 3.

Note: An orchestration template can only contain one healthcheck configuration. If multiple healthcheck configurations exist, only the last healthcheck configuration will take effect.

Orchestration example:

  1. version: '3'
  2. services:
  3. web:
  4. image: wordpress:4
  5. healthcheck:
  6. test: ["CMD", "curl", "-f", "http://localhost"]
  7. interval: 1m30s
  8. timeout: 10s
  9. retries: 3
Thank you! We've received your feedback.