mikenye/docker-healthchecks-framework

This set of scripts provide a framework for creating simple and reliable healthcheck scripts for Docker containers.

• mikenye/docker-healthchecks-framework
  • Adding to your image
  • Adding to your healthcheck script
  • Checks
    • check_tcp4_connection_established_for_pid
    • check_tcp4_connection_established
    • check_udp4_connection_established_pid
    • check_udp4_connection_established
    • check_tcp4_socket_listening_for_pid
    • check_tcp4_socket_listening
    • check_udp4_socket_listening
    • check_s6_service_abnormal_death_tally
  • Helpers
    • get_ipv4

Adding to your image

Clone the repository, and if desired delete files/directories not required, as-per the example below.

    # Deploy healthchecks framework
    git clone \
      --depth=1 \
      https://github.com/mikenye/docker-healthchecks-framework.git \
      /opt/healthchecks-framework \
      && \
    rm -rf \
      /opt/healthchecks-framework/.git* \
      /opt/healthchecks-framework/*.md \
      /opt/healthchecks-framework/tests \
      && \

Adding to your healthcheck script

In your healthcheck script (which should use bash as an interpreter), add the following:

# Import healthchecks-framework
source /opt/healthchecks-framework/healthchecks.sh

You can then call the functions outlined below.

For example, to ensure a web server is listening in your container:

#!/usr/bin/env bash

# Import healthchecks-framework
source /opt/healthchecks-framework/healthchecks.sh

# Ensure web server listening
if ! check_tcp4_socket_listening ANY 80; then
    exit 1
fi

exit 0

You can then set this script in your HEALTHCHECK argument in your project's Dockerfile.

Checks

check_tcp4_connection_established_for_pid

Checks that an IPv4 TCP connection is established for a specific PID.

Dependencies:

• netstat
  • Provided by the net-tools package on Debian/Ubuntu

Syntax:

check_tcp4_connection_established_pid local_ip local_port remote_ip remote_port pid

Arguments:

• local_ip: The IPv4 address of the local side of the connection, or ANY.
• local_port: The TCP port of the local side of the connection, or ANY.
• remote_ip: The IPv4 address of the remote side of the connection, or ANY.
• remote_port: The TCP port of the remote side of the connection, or ANY.
• pid: The PID of the process, or ANY.

Example 1:

Checks to ensure a connection to an external MariaDB database server is always established from a specific PID:

check_tcp4_connection_established_pid ANY ANY 1.2.3.4 3306 "$pid_of_process"

check_tcp4_connection_established

Checks that an IPv4 TCP connection is established.

Dependencies:

• netstat
  • Provided by the net-tools package on Debian/Ubuntu

Syntax:

check_tcp4_connection_established local_ip local_port remote_ip remote_port

Arguments:

• local_ip: The IPv4 address of the local side of the connection, or ANY.
• local_port: The TCP port of the local side of the connection, or ANY.
• remote_ip: The IPv4 address of the remote side of the connection, or ANY.
• remote_port: The TCP port of the remote side of the connection, or ANY.

Example 1:

Checks to ensure a connection to an external MariaDB database server is always established:

check_tcp4_connection_established ANY ANY 1.2.3.4 3306

Example 2:

Check to ensure at least one inbound OpenVPN connecton is always established:

check_tcp4_connection_established ANY 443 ANY ANY

Example 3:

Combined usage with get_ipv4 to resolve a linked container name (in the example below, the container is named "mariadb") to an IP:

check_tcp4_connection_established ANY ANY $(get_ipv4 mariadb) 3306

check_udp4_connection_established_pid

Checks that an IPv4 UDP connection is established for a specific PID.

Dependencies:

• netstat
  • Provided by the net-tools package on Debian/Ubuntu

Syntax:

check_udp4_connection_established_pid local_ip local_port remote_ip remote_port pid

Arguments:

• local_ip: The IPv4 address of the local side of the connection, or ANY.
• local_port: The UDP port of the local side of the connection, or ANY.
• remote_ip: The IPv4 address of the remote side of the connection, or ANY.
• remote_port: The UDP port of the remote side of the connection, or ANY.
• pid: The PID of the process, or ANY.

Example 1:

Checks to ensure a connection to an external RTP server is always established for a specific PID:

check_udp4_connection_established_pid ANY ANY 1.2.3.4 5234 "$process_pid"

check_udp4_connection_established

Checks that an IPv4 UDP connection is established.

Dependencies:

• netstat
  • Provided by the net-tools package on Debian/Ubuntu

Syntax:

check_udp4_connection_established local_ip local_port remote_ip remote_port

Arguments:

• local_ip: The IPv4 address of the local side of the connection, or ANY.
• local_port: The UDP port of the local side of the connection, or ANY.
• remote_ip: The IPv4 address of the remote side of the connection, or ANY.
• remote_port: The UDP port of the remote side of the connection, or ANY.

Example 1:

Checks to ensure a connection to an external RTP server is always established:

check_udp4_connection_established ANY ANY 1.2.3.4 5234

Example 2:

Combined usage with get_ipv4 to resolve a linked container name (in the example below, the container is named "rtmpserver") to an IP:

check_udp4_connection_established ANY ANY $(get_ipv4 rtmpserver) 5234

check_tcp4_socket_listening_for_pid

Checks that an IPv4 TCP socket is listening for a specific PID.

Dependencies:

• netstat
  • Provided by the net-tools package on Debian/Ubuntu

Syntax:

check_tcp4_socket_listening_pid local_ip local_port pid

Arguments:

• local_ip: The local IPv4 address the service is listening on, or ANY.
• local_port: The local TCP port the service is listening on, or ANY.
• pid: The PID of the process, or ANY.

Example 1:

Checks to ensure a web server is always listening on 0.0.0.0:80:

check_tcp4_socket_listening_pid 0.0.0.0 80 "$process_pid"

check_tcp4_socket_listening

Checks that an IPv4 TCP socket is listening.

Dependencies:

• netstat
  • Provided by the net-tools package on Debian/Ubuntu

Syntax:

check_tcp4_socket_listening local_ip local_port

Arguments:

• local_ip: The local IPv4 address the service is listening on, or ANY.
• local_port: The local TCP port the service is listening on, or ANY.

Example 1:

Checks to ensure a web server is always listening on 0.0.0.0:80:

check_tcp4_socket_listening 0.0.0.0 80

Example 2:

Check to ensure a database server is always listening on 127.0.0.1:3306:

check_tcp4_socket_listening 127.0.0.1 3306

check_udp4_socket_listening

Checks that an IPv4 UDP socket is listening.

Dependencies:

• netstat
  • Provided by the net-tools package on Debian/Ubuntu

Syntax:

check_udp4_socket_listening local_ip local_port

Arguments:

• local_ip: The local IPv4 address the service is listening on, or ANY.
• local_port: The local UDP port the service is listening on, or ANY.

Example 1:

Checks to ensure an RTP server is always listening on 0.0.0.0:5234:

check_udp4_socket_listening 0.0.0.0 5234

check_s6_service_abnormal_death_tally

Checks for abnormal service deaths for s6-overlay services.

Dependencies:

• s6-overlay
  • See https://github.com/just-containers/s6-overlay

Syntax:

check_s6_service_abnormal_death_tally service_name service_root

Arguments:

• service_name: The name of the s6 service, or ALL
• service_root: If the root directory is something other than /run/s6/services, otherwise leave unset

Example 1:

Check for abnormal death count for all services in a container:

check_s6_service_abnormal_death_tally ALL

Helpers

get_ipv4

Resolves a host/container to an IPv4 address.

Dependencies:

One of the following:

• dig
  • Provided by the dnsutils package on Debian/Ubuntu
• busybox
  • Provided by the busybox package on Debian/Ubuntu
• s6-dnsip4
  • Provided by s6-overlay

Syntax:

get_ipv4 host

Arguments:

• host: Hostname, container name, FQDN or IPv4 address.

Example 1:

Combined usage with check_tcp4_connection_established to resolve a linked container name (in the example below, the container is named "mariadb") to an IP:

check_tcp4_connection_established ANY ANY $(get_ipv4 mariadb) 3306