Health checks for Docker Compose

To ensure your application is up and running at all times, you can configure health checks for both startup and running phases.

๐Ÿ“˜

Kubernetes probes

Keep in mind that Docker Compose Components are deployed on Kubernetes.

So, health checks for Docker Compose Components are implemented using Kubernetes probes.


Liveness probes

For Kubernetes to decide if a Pod needs to be restarted, you can set up Liveness probes. This is mainly useful if the application reaches a state in which it cannot progress anymore, but the process itself is still running.

In other words, Liveness probes ensure that your application is up and running, and if it's not anymore - if the liveness probe fails - it will restart the Pod which fails the check.


HTTP Liveness probes

You can define an HTTP liveness probe as follows:

components:
    -
        kind: Application
        name: my-component
        ...
        dockerCompose:
        	  ...
            healthcheck:
                interval: 10s
                timeout: 10s
                retries: 3
                start_period: 30s
            labels:
                kompose.service.healthcheck.liveness.http_get_path: /health/ping
                kompose.service.healthcheck.liveness.http_get_port: 8080

Readiness probes

For Kubernetes to decide if a Pod is up and running and can be included in the Service / Load Balancer, you can set up Readiness probes. This is mainly useful when the application starts, and the Pod is not ready to handle traffic, but the container itself is running.

In other words, Readiness probes ensure that your application has started, and if it has not (yet) - if the readiness probe fails - it will not direct traffic to it.


HTTP Readiness probes

You can define a readiness probe using an HTTP check:

components:
    -
        kind: Application
        name: my-component
        ...
        dockerCompose:
            ...
            labels:
                kompose.service.healthcheck.readiness.http_get_path: /health/ping
                kompose.service.healthcheck.readiness.http_get_port: 8080
                kompose.service.healthcheck.readiness.interval: 10s
                kompose.service.healthcheck.readiness.timeout: 10s
                kompose.service.healthcheck.readiness.retries: 5
                kompose.service.healthcheck.readiness.start_period: 1s

Parameters:

  • kompose.service.healthcheck.readiness.http_get_path defines the path (on localhost) to be fetched
  • kompose.service.healthcheck.readiness.http_get_port defines the port (on localhost) to be fetched
  • kompose.service.healthcheck.readiness.interval specifies the frequency of checks
  • kompose.service.healthcheck.readiness.timeout is the time the test will wait for the script to be executed - default: 1
  • kompose.service.healthcheck.readiness.retries specifies the number of consecutive fails needed to mark the service as unavailable and stop routing traffic to it - default: 3
  • kompose.service.healthcheck.readiness.start_period is an initial period in which checks are not executed - optional

Command Readiness probes

You can define a readiness probe also using a command. The command must return 0 when the service is ready to receive traffic, or non-0 exit codes otherwise. The test will be executed at the specified interval, and when the script exits with 0 the Pod will start to receive traffic.

An example using a cURL is featured, but you can run any command, including executing a script which can be found in the container image.

components:
    -
        kind: Application
        name: my-component
        ...
        dockerCompose:
            ...
            labels:
                kompose.service.healthcheck.readiness.test: 'CMD curl -f "http://localhost:8080/"'
                kompose.service.healthcheck.readiness.interval: 10s
                kompose.service.healthcheck.readiness.timeout: 10s
                kompose.service.healthcheck.readiness.retries: 5
                kompose.service.healthcheck.readiness.start_period: 1s
                

๐Ÿ“˜

You can set the test command to run a script, eg:
kompose.service.healthcheck.readiness.test: 'CMD /readiness-check.sh'.

Parameters:

  • kompose.service.healthcheck.readiness.test defines the test to be ran
  • kompose.service.healthcheck.readiness.interval specifies the frequency of checks
  • kompose.service.healthcheck.readiness.timeout is the time the test will wait for the script to be executed - default: 1
  • kompose.service.healthcheck.readiness.retries specifies the number of consecutive fails needed to mark the service as unavailable and stop routing traffic to it - default: 3
  • kompose.service.healthcheck.readiness.start_period is an initial period in which checks are not executed - optional