How (and because) add health checks to your Docker containers

You have created your Docker image, you have submitted it to your registry and started a new container in production. Everything works as you come home for the day, but you run into reports of outages when you return the next morning. Your container is still running, but it does not attend requests.

This scenario can be uncomfortable for operations teams working with Docker. Next, Here's how to use Docker's health check feature to get accurate data on the availability of your services.

How Health Checks Work

Health checks allow a container to expose the availability of your workload. This is distinguished from whether the container is in a hurry. If your database stops working, your API server will not be able to handle requests, even though your Docker container is still running.

This creates useless experiences during troubleshooting. A simple docker ps would report the container as available. Adding a health check extends the docker ps output to include the true state of the container.

Configure container health checks in your Dockerfile. This accepts a command that the Docker daemon will run every 30 seconds. Docker uses the command's exit code to set the health of its container:

• 0 – The container is healthy and functioning normally.
• 1 – The container is not healthy; the workload may not be working.
• 2 – This status code is reserved by Docker and should not be used.

When HEALTHCHECK is present in a Dockerfile, you will see the healthiness of the container in the STATUS column when you run docker ps.

Health is not immediately checked when containers are created. Status will show as starting before the first check is run. This gives the container time to run any startup tasks. A container with a passed health check will show up as healthy; shows an unhealthy container unhealthy.

Write status check commands

Container health checks are configured with the HEALTHCHECK instruction in your Dockerfile. you must use a status check command that is appropriate for your container. For web servers, curl gives you a simple way to perform a basic readiness check. Ping a known endpoint that should be available whenever your service is active.

FROM nginx:latest
HEALTHCHECK CMD curl --fail http://localhost/api/healthcheck || exit 1

this example would mark the container as unhealthy if your server /api/healthcheck the endpoint issued an error state.

You can use docker inspect to view the result of the status check commands. This is useful when you are debugging your HEALTHCHECK instruction.

docker inspect --format="{{json . State.Health}}" my-container

Replace my-container with the identification or name of the container you want to inspect. These details are displayed in docker ps production.

Customizing health checks

Docker enables you to customize the frequency of health checks. You can also modify the criteria that mark a container as unhealthy.

There are four options available:

• --interval – Determine the time between health checks. This enables you to override the default value of 30 seconds. Use a higher interval to increase the time between checks. This helps if you have a low priority service where regular health checks can affect performance. Use a more regular frequency for critical services.
• --start-period – Set the duration after a container starts when health checks should be ignored. The command will continue to run, but an incorrect state will not be counted. This gives the containers time to complete the startup procedures.
• --retries – This enables you to require multiple successive failures before a container is marked as unhealthy. The default is 3. If a health check fails but the next one passes, the container will not pass to unhealthy. Will become unhealthy after three consecutive failed checks.
• --timeout – Determine the timeout for health check commands. docker will treat the verification as failed if the command does not exit within this time period.

The alternatives are passed like flags to the HEALTHCHECK instruction. Supply them before the status check command:

HEALTHCHECK --interval=60s --retries=5 CMD curl --fail http://localhost || exit 1

This setting instructs Docker to run curl each 60 seconds. The container will be marked as unhealthy if five consecutive tests have a non-zero exit code.

Command format

the HEALTHCHECK the command syntax supports a simple CMD or an entry point style exec training. You can also pass NONE instead of CMD to disable health checks:

HEALTHCHECK NONE

This enables you to inhibit health checks of your base image. Each HEALTHCHECK statement overrides any previous statement on your image layers.

What about Docker Compose?

Docker Compose also supports health check definitions. Add a healthcheck section at your service :.

version: "3"
services:
  app:
    image: nginx:latest
    ports:
      - 80:80
    healthcheck:
      test: curl --fail http://localhost || exit 1
      interval: 10s
      retries: 5
      start_period: 5s
      timeout: 10s

the test key sets the command to execute. The other keys are mapped to the parameters accepted by Dockerfile HEALTHCHECK instruction.

Summary

Determine a HEALTHCHECK Instruction makes it easy to diagnose a misbehaving container. You can track the readiness of your workload regardless of status “in action” of the container.

Health checks are supported by any command that issues a 0 O 1 exit code. You can use common commands like curl and ping to inspect databases and web services. For more advanced control, write a dedicated script and include it in your images.