personal_infra/ansible/roles/healthcheck/tasks/main.yml

79 lines
2.7 KiB
YAML
Raw Normal View History

monitoring: recover host checks for the whole estate, reported to Gatus Five checks, 27 endpoints, replacing what Uptime Kuma used to watch: is it up every 5min, all hosts is disk full daily, all hosts is CPU hot every 5min, nodito is ZFS broken daily, nodito is UPS online every 5min, nodito Two roles, kept separate so neither knows about the other - they meet at a URL and a token, the same way caddy_site and each service meet at a vhost: roles/gatus_endpoint runs on the observability host, writes ONE file into /opt/gatus/config/endpoints/. Gatus merges every *.yaml there and appends lists, so callers compose without coordinating. roles/healthcheck runs on the monitored host: a check script, a systemd service, a timer, and an optional push. Ships a library of check bodies under templates/checks/. Everything PUSHES. Gatus never reaches out, which matters because nodito and its VMs are behind NAT, and because four of the five checks are internal state with no pollable surface at all. Liveness pushes too, deliberately: a heartbeat proves the host is running AND can reach the internet, where an ICMP probe from one vantage point only proves it answers pings from there. And since Gatus alerts when a heartbeat window expires, a check that stops running raises the alarm by itself - a dead timer looks exactly like a dead host, which is the correct reading. One bearer token per host, generated straight into the vault and never printed. A token only writes results for its own host's endpoints, so a compromised host can lie about itself, which it could do anyway. Three things learned from the source that shaped this: * Gatus polls its own config every 30s and reloads (main.listenToConfigurationFileChanges), so gatus_endpoint needs no restart handler - writing the file IS the deploy. * ...but on a reload it panics if the new config fails to parse, unless skip-invalid-config-update is set. Endpoint files are contributed by other playbooks, so one malformed file would take the monitor down at the worst possible moment. Now set. * The push URL uses a key Gatus computes, not the name you write: sanitize(group) + "_" + sanitize(name), lowercased with / _ . , space # + & replaced by "-" (config/key/key.go). So knots_box_local is knots-box-local in the URL. The playbook derives it rather than hand-writing. storage: maximum-number-of-results 900, up from upstream's 100. Gatus bounds the database by COUNT and trims inline on insert, so there is no retention job and no way to fill a disk - but history depth is then a function of check frequency, and 100 results at a 5-minute interval is 8 hours. 900 is ~3 days of liveness and ~2.5 years of the daily disk check. The uptime table is separate and its 30-day retention is hard-coded upstream. A bug worth recording: the first deploy shipped five scripts that all died with "syntax error: unexpected end of file". Jinja strips an included template's trailing newline and trim_blocks then eats the newline after {% endif %}, so the closing brace of check() landed on the same line as the body's last statement - `return 0}`. Every check was broken and the deploy still reported failed=0, because the role's "run once" task has failed_when: false and reports the result as a debug message nobody read. The blank line that fixes it is now load-bearing and commented as such. Verified by triggering every unit by hand rather than waiting on timers: all checks exit 0 on all hosts, and Gatus shows 26 UP / 1 DOWN. The one DOWN is liveness_watchtower, which is honest - that host currently refuses SSH (TCP connects, no banner exchange) and is excluded from this deploy. It is also the box still running Uptime Kuma. Known waste, not yet fixed: healthcheck installs its dependencies per CHECK rather than per HOST, so apt runs 29 times estate-wide for a curl that is already present, and daemon_reload runs 4x per host. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-09-14 08:54:10 +02:00
---
- name: "Assert healthcheck '{{ healthcheck_name }}' is fully specified"
ansible.builtin.assert:
that:
- healthcheck_name | length > 0
- healthcheck_description | length > 0
- (healthcheck_check | length > 0) != (healthcheck_command | length > 0)
- not (healthcheck_push_url | length > 0) or (healthcheck_push_token | length > 0)
fail_msg: >-
healthcheck needs a name, a description, exactly one of healthcheck_check
or healthcheck_command, and a token whenever a push URL is set. A push URL
with no token would report to Gatus and be rejected 401 on every run.
- name: Install healthcheck dependencies
ansible.builtin.package:
name: "{{ healthcheck_packages | default(['curl']) }}"
state: present
- name: Create the healthcheck log directory
ansible.builtin.file:
path: "{{ healthcheck_log_dir }}"
state: directory
owner: root
group: root
mode: "0750"
- name: "Install the {{ healthcheck_name }} check script"
ansible.builtin.template:
src: healthcheck.sh.j2
dest: "{{ healthcheck_script_dir }}/{{ healthcheck_name }}-healthcheck.sh"
owner: root
group: root
mode: "0755"
# The token is in this unit file, so it must not be world-readable.
- name: "Install the {{ healthcheck_name }} systemd service"
ansible.builtin.template:
src: healthcheck.service.j2
dest: "/etc/systemd/system/{{ healthcheck_name }}-healthcheck.service"
owner: root
group: root
mode: "0600"
- name: "Install the {{ healthcheck_name }} systemd timer"
ansible.builtin.template:
src: healthcheck.timer.j2
dest: "/etc/systemd/system/{{ healthcheck_name }}-healthcheck.timer"
owner: root
group: root
mode: "0644"
- name: Reload systemd
ansible.builtin.systemd:
daemon_reload: yes
# `restarted`, not `started`: started is a no-op on an already-active timer, so
# a changed interval or a stuck timer would never be picked up.
- name: "Enable and start the {{ healthcheck_name }} timer"
ansible.builtin.systemd:
name: "{{ healthcheck_name }}-healthcheck.timer"
enabled: yes
state: restarted
daemon_reload: yes
- name: "Run the {{ healthcheck_name }} check once now"
ansible.builtin.command: "{{ healthcheck_script_dir }}/{{ healthcheck_name }}-healthcheck.sh"
environment:
HEALTHCHECK_PUSH_URL: "{{ healthcheck_push_url }}"
HEALTHCHECK_PUSH_TOKEN: "{{ healthcheck_push_token }}"
register: healthcheck_first_run
changed_when: false
failed_when: false
- name: "Report the first {{ healthcheck_name }} result"
ansible.builtin.debug:
msg: >-
{{ healthcheck_name }}: {{ 'HEALTHY' if healthcheck_first_run.rc == 0
else 'UNHEALTHY (rc=' ~ healthcheck_first_run.rc ~ ')' }}