100 lines
10 KiB
Markdown
100 lines
10 KiB
Markdown
<!--
|
|
Ansible Roles for managing Auengun.net Infrastructure & Testing/Learning.
|
|
Source available at git.auengun.net/homelab/ansible-collection
|
|
Copyright (C) 2023 GregoryDosh
|
|
|
|
This program is free software: you can redistribute it and/or modify
|
|
it under the terms of the GNU Affero General Public License as
|
|
published by the Free Software Foundation, either version 3 of the
|
|
License, or (at your option) any later version.
|
|
|
|
This program is distributed in the hope that it will be useful,
|
|
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
GNU Affero General Public License for more details.
|
|
|
|
You should have received a copy of the GNU Affero General Public License
|
|
along with this program. If not, see <https://www.gnu.org/licenses/>.
|
|
|
|
SPDX-License-Identifier: AGPL-3.0-or-later
|
|
SPDX-FileCopyrightText: 2023 GregoryDosh
|
|
-->
|
|
|
|
# Ansible Role `auengun.homelab.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.
|
|
|
|
## Installation
|
|
|
|
Read the [Homelab Collection README.md](../../README.md) for installation instructions.
|
|
|
|
### 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: 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
|
|
|
|
```yaml
|
|
- 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
|
|
```
|