ansible-playbooks/roles/monitoring/README.md

Rolle monitoring

Installiert und konfiguriert den Zabbix Agent 2 auf Debian-Hosts, generiert/verteilt pro Host eine TLS-PSK, konfiguriert das Docker-Plugin (bei vorhandenem Socket) und registriert den Host über die Zabbix-API einschließlich Template-Verlinkung.

Siehe auch das Playbook playbooks/monitoring.yml sowie die Repo-README.

Voraussetzungen

• Debian-Ziel-Host
• Erreichbarer Zabbix-Server (API & Agent-Polling)
• community.zabbix Collection
• Vault-Secret monitoring_zabbix_api_password in vault.yml
• OpenSSL auf dem Ansible-Controller (für PSK-Generierung)

Einbindung

- hosts: all
  become: true
  user: admin
  roles:
    - role: monitoring

ansible-playbook -i inventory/dmc12.yml --vault-password-file .vault_password \
  playbooks/monitoring.yml

Funktionsweise

tasks/main.yml importiert die Subtasks in folgender Reihenfolge (alle mit Tag monitoring):

1. validate.yml – bricht bei Nicht-Debian ab, prüft dass monitoring_zabbix_passive_servers gesetzt ist und (bei aktivierter Registrierung) API-URL/-User/-Passwort vorliegen. Stellt sicher, dass bei gesetztem monitoring_zabbix_proxy auch eine Proxy-Adresse definiert ist.
2. install-repository.yml – installiert ca-certificates, lädt das Zabbix-Release-Paket herunter, installiert es und aktualisiert den apt-Cache.
3. install-agent.yml – installiert zabbix-agent2 und aktiviert/startet den Service.
4. configure-docker.yml – prüft, ob der Docker-Socket existiert. Falls ja: Zabbix-User zur Docker-Gruppe hinzufügen, Plugin-Config-Verzeichnis anlegen, docker.conf aus Template ausliefern. Falls nein: Plugin-Config entfernen.
5. configure-psk.yml – stellt PSK-Store auf dem Controller sicher (<playbook_dir>/../.zabbix-psk), generiert pro Host eine PSK mit openssl rand -hex, persistiert sie im Store und verteilt sie auf den Zielhost (/etc/zabbix/zabbix_agent2.psk, Mode 0600).
6. configure-agent.yml – schreibt zabbix_agent2.conf aus Template.
7. register-host.yml – registriert bzw. aktualisiert den Host über die Zabbix-API (community.zabbix.zabbix_host). Verknüpft Standard-Templates und ggf. Docker-Templates. Unterscheidet zwischen Proxy- und Server-Modus (zwei Tasks, gegeneinander exklusiv). Delegiert an localhost.

Variablen

Zabbix-Agent

Variable	Typ	Default	Beschreibung
monitoring_zabbix_version	string	7.0	Zabbix-Hauptversion
monitoring_zabbix_release_package	string	abgeleitet	Dateiname des Release-Pakets
monitoring_zabbix_release_url	string	abgeleitet	Download-URL des Release-Pakets
monitoring_zabbix_release_path	string	/tmp/<package>	lokaler Ablagepfad auf dem Zielhost
monitoring_zabbix_agent_package	string	zabbix-agent2	Zu installierendes Agent-Paket
monitoring_zabbix_agent_service	string	zabbix-agent2	systemd-Service-Name
monitoring_zabbix_config_file	string	/etc/zabbix/zabbix_agent2.conf	Pfad zur Agent-Konfiguration
monitoring_zabbix_agent_user	string	zabbix	Benutzer, unter dem der Agent läuft
monitoring_zabbix_passive_servers	list	["192.168.212.1"]	Erlaubte Server für passive Checks (Server=)
monitoring_zabbix_active_servers	list	""	Server für aktive Checks (ServerActive=)
monitoring_zabbix_listen_port	int	10050	Listen-Port des Agents

Docker-Plugin

Variable	Typ	Default	Beschreibung
monitoring_zabbix_docker_group	string	docker	Docker-Gruppe für Socket-Zugriff
monitoring_zabbix_docker_socket_path	string	/var/run/docker.sock	Pfad zum Docker-Socket
monitoring_zabbix_docker_plugin_config_file	string	/etc/zabbix/zabbix_agent2.d/plugins.d/docker.conf	Pfad zur Plugin-Config
monitoring_zabbix_docker_endpoint	string	unix://<socket>	Docker-Endpoint für das Plugin

TLS / PSK

Variable	Typ	Default	Beschreibung
monitoring_zabbix_tls_connect	string	psk	TLS-Modus für ausgehende Verbindungen
monitoring_zabbix_tls_accept	string	psk	TLS-Modus für eingehende Verbindungen
monitoring_zabbix_psk_identity	string	{{ inventory_hostname }}	PSK-Identity (hostname)
monitoring_zabbix_psk_file	string	/etc/zabbix/zabbix_agent2.psk	Pfad zur PSK-Datei auf dem Zielhost
monitoring_zabbix_psk_bits	int	256	PSK-Länge in Bits (32 Byte → 64 Hex-Chars)
monitoring_zabbix_psk_store	string	{{ playbook_dir }}/../.zabbix-psk	PSK-Store-Verzeichnis auf dem Controller
monitoring_zabbix_psk_store_mode	string	0700	Berechtigung des PSK-Stores

Zabbix Proxy (optional)

Variable	Typ	Default	Beschreibung
monitoring_zabbix_proxy	string	""	Name des Proxys in Zabbix (leer = direkter Server-Modus)
monitoring_zabbix_proxy_address	string	""	IP/DNS des Proxys, den der Agent kontaktiert

Zabbix API / Host-Registrierung

Variable	Typ	Default	Beschreibung
monitoring_zabbix_api_url	string	https://zabbix/api_jsonrpc.php	API-URL
monitoring_zabbix_api_user	string	Admin	API-Benutzer
monitoring_zabbix_api_password	string	(Vault)	API-Passwort – MUSS in vault.yml gesetzt werden
monitoring_zabbix_api_validate_certs	bool	true	TLS-Zertifikate prüfen
monitoring_zabbix_register_host	bool	true	Host automatisch registrieren
monitoring_zabbix_host_name	string	{{ inventory_hostname }}	Hostname in Zabbix
monitoring_zabbix_host_groups	list	["Linux servers"]	Zabbix-Host-Gruppen
monitoring_zabbix_host_interface_ip	string	{{ ansible_host }}	Interface-IP
monitoring_zabbix_host_interface_port	string	{{ monitoring_zabbix_listen_port }}	Interface-Port
monitoring_zabbix_host_inventory_mode	string	manual	Inventory-Modus
monitoring_zabbix_templates	list	["Linux by Zabbix agent", "Zabbix agent2"]	Standard-Templates
monitoring_zabbix_docker_templates	list	["Docker by Zabbix agent2"]	Zusätzliche Templates bei vorhandenem Docker-Socket

Inventory-Overrides

In inventory/group_vars/home.yml werden u. a. überschrieben: monitoring_zabbix_passive_servers, monitoring_zabbix_active_servers, monitoring_zabbix_api_url, monitoring_zabbix_host_groups, monitoring_zabbix_templates, monitoring_zabbix_docker_templates, monitoring_zabbix_proxy, monitoring_zabbix_proxy_address.

Templates

Template	Ziel
zabbix_agent2.conf.j2	/etc/zabbix/zabbix_agent2.conf
docker.conf.j2	/etc/zabbix/zabbix_agent2.d/plugins.d/docker.conf

zabbix_agent2.conf.j2 berücksichtigt Proxy-Konfiguration (vereinigt Passive-Servers mit Proxy-Adresse, setzt ServerActive auf Proxy).

Handler

Handler	Auslöser
Restart Zabbix Agent	Änderungen an Config, PSK oder Docker-Plugin

Tags

monitoring – alle Subtasks sind mit diesem Tag versehen:

ansible-playbook -i inventory/dmc12.yml playbooks/monitoring.yml -t monitoring

Abhängigkeiten

• community.zabbix Collection (zabbix_host-Modul)
• ansible.builtin (Bordmittel)
• OpenSSL auf dem Controller (für PSK-Generierung)

Hinweise

• PSK-Store: Pro Host wird eine PSK unter <playbook_dir>/../.zabbix-psk/<hostname>.psk (git-ignored) gespeichert. Bei Host-Umbenennung PSK migrieren oder neu generieren – sonst stimmt die Zabbix-Registrierung nicht.
• API-Passwort MUSS in vault.yml als monitoring_zabbix_api_password gesetzt sein; die Validate-Tasks brechen sonst ab.
• Docker-Plugin wird nur konfiguriert, wenn der Socket existiert – sonst wird eine eventuell vorhandene Plugin-Config entfernt (Idempotenz).
• Die Registrierung wird delegiert an localhost ausgeführt, da der Controller den API-Zugang besitzt.
• Proxy- und Server-Modus schließen sich gegenseitig aus (zwei Tasks mit entgegengesetzten when-Bedingungen).