79 lines
9.2 KiB
Markdown
79 lines
9.2 KiB
Markdown
<!--
|
|
SPDX-License-Identifier: AGPL-3.0-or-later
|
|
SPDX-FileCopyrightText: 2025 Dosh LLC
|
|
-->
|
|
|
|
# Ansible Role `dosh_llc.ansible_cron.healthcheck_script`
|
|
|
|
This role creates (and keeps updated) a [`crontab`](https://www.man7.org/linux/man-pages/man5/crontab.5.html) entry for a user defined Bash script which is automatically wrapped with a [Healthcheck.io](https://healthchecks.io) ([healthchecks.auengun.net](https://healthchecks.auengun.net)) enabled start/stop/status/data check.
|
|
|
|
### Ansible Configuration
|
|
|
|
This Ansible role uses the following [`vars`](https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_variables.html).
|
|
|
|
| Ansible `vars:` Name | Description | Required | Default |
|
|
| --------------------------- | ----------------------------------------------------------------------------------------------------------------- | :------: | -------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| `HEALTHCHECK_SITE_URL` | [Healthchecks.io `v2` checks endpoint](https://healthchecks.io/docs/apiv2/) to use | ❌ | `https://healthchecks.auengun.net/api/v2/checks/` |
|
|
| `HEALTHCHECK_SITE_API_KEY` | The [Healthchecks.io](https://healthchecks.io/docs/apiv2/) project API key to use. | ✅ | |
|
|
| `HEALTHCHECK_NAME` | The human facing name for this healthcheck. | ❌ | `Healthcheck - {{ inventory_hostname_short }}` |
|
|
| `HEALTHCHECK_CRON_USER` | `crontab` [`username`](https://www.man7.org/linux/man-pages/man5/crontab.5.html) field. | ❌ | `{{ ansible_user }}` |
|
|
| `HEALTHCHECK_CRON_MINUTE` | `crontab` [`minute`](https://www.man7.org/linux/man-pages/man5/crontab.5.html) field. | ❌ | `{{ 59 \| random(seed=HEALTHCHECK_NAME) }}` |
|
|
| `HEALTHCHECK_CRON_HOUR` | `crontab` [`hour`](https://www.man7.org/linux/man-pages/man5/crontab.5.html) field. | ❌ | `*` |
|
|
| `HEALTHCHECK_CRON_DAY` | `crontab` [`day`](https://www.man7.org/linux/man-pages/man5/crontab.5.html) field. | ❌ | `*` |
|
|
| `HEALTHCHECK_CRON_MONTH` | `crontab` [`month`](https://www.man7.org/linux/man-pages/man5/crontab.5.html) field. | ❌ | `*` |
|
|
| `HEALTHCHECK_CRON_WEEKDAY` | `crontab` [`weekday`](https://www.man7.org/linux/man-pages/man5/crontab.5.html) field. | ❌ | `*` |
|
|
| `HEALTHCHECK_SCHEDULE` | The composite [`cron` Healthcheck schedule](https://healthchecks.io/docs/apiv2/). | ❌ | `{{ HEALTHCHECK_CRON_MINUTE }} {{ HEALTHCHECK_CRON_HOUR }} {{ HEALTHCHECK_CRON_DAY }} {{ HEALTHCHECK_CRON_MONTH }} {{ HEALTHCHECK_CRON_WEEKDAY }}` |
|
|
| `HEALTHCHECK_SCHEDULE_TZ` | The [Healthcheck schedule timezone](https://healthchecks.io/docs/apiv2/). | ❌ | `Etc/UTC` |
|
|
| `HEALTHCHECK_GRACE` | The [Healthcheck schedule grace period](https://healthchecks.io/docs/apiv2/). | ❌ | `600` |
|
|
| `HEALTHCHECK_TAGS` | The [Healthcheck tags](https://healthchecks.io/docs/apiv2/). | ❌ | `{{ 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`<br/> `/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](#script-configuration) below) | ✅ | |
|
|
|
|
### Script Configuration
|
|
|
|
The [`HEALTHCHECK_FILE_CONTENT`](#ansible-configuration) 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](https://www.man7.org/linux/man-pages/man1/curl.1.html) <br/>Common options:<br/>`Content-Type: application/json`<br/>`Content-Type: text/plain` | `Content-Type: text/plain` |
|
|
| `EXIT_STATUS` | The exit status code reported back to the [Healthcheck Pinging API](https://healthchecks.io/docs/http_api/) | `0` |
|
|
|
|
## Examples
|
|
|
|
### Basic NVIDIA GPU driver sanity check
|
|
|
|
```yaml
|
|
- ansible.builtin.include_role:
|
|
name: dosh_llc.ansible_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
|
|
|
|
```yaml
|
|
- ansible.builtin.include_role:
|
|
name: dosh_llc.ansible_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
|
|
```
|