ansible-collection/roles/cron_healthcheck_script

Ansible Role auengun.homelab.cron_healthcheck_script

This role creates (and keeps updated) a crontab entry for a user defined Bash script which is automatically wrapped with a Healthcheck.io (healthchecks.auengun.net) enabled start/stop/status/data check.

Installation

Read the Homelab Collection README.md for installation instructions.

Ansible Configuration

This Ansible role uses the following vars.

Ansible vars: Name	Description	Required	Default
HEALTHCHECK_SITE_URL	Healthchecks.io v2 checks endpoint to use	❌	https://healthchecks.auengun.net/api/v2/checks/
HEALTHCHECK_SITE_API_KEY	The Healthchecks.io project API key to use.	✅
HEALTHCHECK_NAME	The human facing name for this healthcheck.	❌	Healthcheck - {{ inventory_hostname_short }}
HEALTHCHECK_CRON_USER	crontab username field.	❌	{{ ansible_user }}
HEALTHCHECK_CRON_MINUTE	crontab minute field.	❌	{{ 59 | random(seed=HEALTHCHECK_NAME) }}
HEALTHCHECK_CRON_HOUR	crontab hour field.	❌	*
HEALTHCHECK_CRON_DAY	crontab day field.	❌	*
HEALTHCHECK_CRON_MONTH	crontab month field.	❌	*
HEALTHCHECK_CRON_WEEKDAY	crontab weekday field.	❌	*
HEALTHCHECK_SCHEDULE	The composite cron Healthcheck schedule.	❌	{{ HEALTHCHECK_CRON_MINUTE }} {{ HEALTHCHECK_CRON_HOUR }} {{ HEALTHCHECK_CRON_DAY }} {{ HEALTHCHECK_CRON_MONTH }} {{ HEALTHCHECK_CRON_WEEKDAY }}
HEALTHCHECK_SCHEDULE_TZ	The Healthcheck schedule timezone.	❌	Etc/UTC
HEALTHCHECK_GRACE	The Healthcheck schedule grace period.	❌	600
HEALTHCHECK_TAGS	The Healthcheck tags.	❌	{{ inventory_hostname_short }}
HEALTHCHECK_FILE_BASEPATH	Location on the system to place the composite Healthcheck script.	❌	/usr/local/sbin if HEALTHCHECK_CRON_USER is root /usr/local/bin otherwise
HEALTHCHECK_FILE_NAME	File name of the Healthcheck script.	❌	healthcheck.sh
HEALTHCHECK_FILE_USER	File user/owner of the Healthcheck script.	❌	{{ HEALTHCHECK_CRON_USER }}
HEALTHCHECK_FILE_GROUP	File group of the Healthcheck script.	❌	{{ HEALTHCHECK_CRON_USER }}
HEALTHCHECK_FILE_MODE	File permissions.	❌	0755
HEALTHCHECK_FILE_CONTENT	User defined logic to be wrapped by Healthcheck script. (see Script Configuration below)	✅

Script Configuration

The HEALTHCHECK_FILE_CONTENT Ansible variable above is enhanced by some common features of the script to make reporting back to Healthchecks a bit easier.

By setting the following environmental variables the existing functionality of the Healthcheck script can be enhanced to report back script failures or change the body of the healthcheck from plain-text to JSON or other formats.

Script Env Var Name	Description	Default
HEALTHCHECK_CONTENT_HEADER	curl Content-Type Common options: Content-Type: application/json Content-Type: text/plain	Content-Type: text/plain
EXIT_STATUS	The exit status code reported back to the Healthcheck Pinging API	0

Examples

Basic NVIDIA GPU driver sanity check

- ansible.builtin.include_role:
    name: auengun.homelab.cron_healthcheck_script
  vars:
    HEALTHCHECK_NAME: "NVIDIA - Host GPU - 🔎"
    HEALTHCHECK_TAGS: "{{ inventory_hostname_short }} 🎬 🔎"
    HEALTHCHECK_FILE_NAME: hc-nvidia-gpu-check
    HEALTHCHECK_FILE_CONTENT: |
      nvidia-smi
      EXIT_STATUS="$?"

Simple Check if Adblocking Up/Down

- ansible.builtin.include_role:
    name: auengun.homelab.cron_healthcheck_script
  vars:
    HEALTHCHECK_NAME: "Network Adblocking - 🔎"
    HEALTHCHECK_TAGS: "{{ inventory_hostname_short }} adblocking 🔎"
    HEALTHCHECK_FILE_NAME: hc-ad-block
    HEALTHCHECK_FILE_CONTENT: |
      CHECK_DOMAIN="doubleclick.net."
      if [ "$(dig +short ${CHECK_DOMAIN})" != "0.0.0.0" ]; then
        echo "ads are not blocked for ${CHECK_DOMAIN}"
        dig +short ${CHECK_DOMAIN}
        EXIT_STATUS=1
      fi