Using the Docker Healthcheck Command

One of the new features in Docker 1.12 is how health check for a container can be baked into the image definition. And this can be overridden at the command line. Just like the CMD instruction, there can be multiple HEALTHCHECK instructions in Dockerfile but only the last one is effective.

This is a great addition because a container reporting status as Up 1 hour may return errors. The container may be up but there is no way for the application inside the container to provide a status. This instruction fixes that.

The Dockerfile that builds arungupta/couchbase image is:

It uses configure-node.sh script to configure the server using Couchbase REST API. The new instruction to notice here is HEALTHCHECK. This instruction can be specified as:

The can be:

• --interval=DURATION (default 30s)
• --timeout=DURATION (default 30s)
• --retries=N (default 3)

The is the command that runs inside the container to check it’s health. If health check is enabled, then the container can have three states:

• starting – Initial status when the container is still starting
• healthy – If the command succeeds then the container is healthy
• unhealthy – If a single run of the  takes longer than the specified timeout then it is considered unhealthy. If a health check fails, retries will be run several times and the Docker container status will be declared unhealthy if it still fails.

The Docker commands exit status indicates the HEALTHCHECK status of the container. The following values are allowed:

• 0 – container is healthy
• 1 – container is not healthy

In our instruction, /pools REST API is invoked using curl. If the command fails then an exit status of 1 is returned, and this marks the container unhealthy for that attempt. This Docker HEALTHCHECK command is invoked every 5 seconds. The container is marked unhealthy if the command does not return successfully within 3 seconds. Run the container as:

Check Docker container status:

Notice how health: starting status is reported in the STATUS column. Checking after a few seconds shows the status:

And now it’s reported healthy. More details about this HEALTHCHECK instruction can be found on docs.docker.com. Now, if you are running an image that does not have HEALTHCHECK instruction then the docker run command can be used to specify similar values. An equivalent runtime command would be:

Last 5 health checks for a container can be obtained using the docker inspect command:

The output is shown as: