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](../../README.md).

## 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

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

```bash
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:

```bash
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).