# Monitoring

## Übersicht

Diese Kategorie umfasst alle Playbooks und Rollen zur CheckMK-Monitoring-Integration. CheckMK wird für die zentrale Überwachung aller verwalteten Systeme eingesetzt.

**Anwendungsfälle**:
- Installation und Registrierung des CheckMK-Agenten auf neuen Hosts
- Neuinstallation von CheckMK-Agenten nach Problemen
- Automatische Service-Discovery auf überwachten Hosts
- Bereinigung von Agent-Plugins
- Verwaltung von Hosts im CheckMK-Server

**CheckMK-Server**: `servercow.observer` (Site: `scowmon`)

---

## Playbooks

### setup-checkmk-monitoring.yml

Umfassende CheckMK-Monitoring-Einrichtung mit Host-Erstellung, Agent-Installation und Service-Discovery.

**Datei**: `playbooks/setup-checkmk-monitoring.yml`

**Zweck**: Vollständige Integration eines neuen Hosts in das CheckMK-Monitoring-System, einschließlich Host-Registrierung, Agent-Installation, Zertifikat-Signierung und automatischer Service-Erkennung.

**Ziel-Hosts**: `all`

**Benutzer**: `tincadmin` (mit sudo-Rechten)

**Verwendete Rollen**:
- `checkmk-monitoring` (eigene Rolle)
  - Tasks: `create-host`, `sign-bake-agents`, `discover-host`
- `checkmk.general.agent` (externe Collection)

**Wichtige Variablen**:

Alle Variablen werden aus der Vault-Datei geladen. Wichtige Konfigurationsparameter:

| Variable | Beispielwert | Beschreibung |
|----------|--------------|-------------|
| `checkmk_server` | `servercow.observer` | CheckMK-Server-URL |
| `checkmk_site` | `scowmon` | CheckMK-Site-Name |
| `checkmk_folder` | `/managed_mailcows` | Ziel-Ordner im CheckMK |
| `checkmk_automation_user` | Aus Vault | Automation-Benutzer |
| `checkmk_automation_secret` | Aus Vault | Automation-Passwort |

**Verwendungsbeispiel**:

```bash
# Vollständiges Monitoring-Setup für alle Hosts
ansible-playbook playbooks/setup-checkmk-monitoring.yml \
  -i inventories/icp-fra-pve1.yml \
  -K --ask-vault-pass

# Nur für bestimmte Host-Gruppe
ansible-playbook playbooks/setup-checkmk-monitoring.yml \
  -i inventories/extern.yml \
  -K --ask-vault-pass

# Einzelner Host
ansible-playbook playbooks/setup-checkmk-monitoring.yml \
  -i inventories/icp-fra-pve1.yml \
  --limit newhost.example.com \
  -K --ask-vault-pass
```

**Abhängigkeiten**:
- Vault-Datei (`vault.yml`) mit CheckMK-Zugangsdaten
- Externe Collection: `checkmk.general`
- Erreichbarkeit des CheckMK-Servers
- DNS-Auflösung für überwachte Hosts

**Besonderheiten**:
- **Mehrere sequenzielle Schritte**:
  1. Host im CheckMK registrieren
  2. Agent-Zertifikate signieren und backen
  3. CheckMK-Agent auf Host installieren
  4. Service-Discovery durchführen
- **2-Minuten-Pause** vor Discovery für Agent-Bereitschaft
- **`ignore_errors: true`** für Agent-Zertifikat-Handling (Fehlertoleranz)
- **Delegation zu localhost** für CheckMK-API-Aufrufe

**Workflow**:
1. Lädt Vault-Datei mit Zugangsdaten
2. Erstellt Host im CheckMK-Server (Task: `create-host`)
3. Signiert und bäckt ausstehende Agent-Jobs (Task: `sign-bake-agents`)
4. Installiert CheckMK-Agent auf Zielhost (externe Rolle)
5. Wartet 2 Minuten auf Agent-Bereitschaft
6. Führt Service-Discovery durch (Task: `discover-host`)
7. Aktiviert Änderungen im CheckMK

---

### reinstall-cmk-agent.yml

Neuinstallation und Neuregistrierung des CheckMK-Monitoring-Agenten.

**Datei**: `playbooks/reinstall-cmk-agent.yml`

**Zweck**: Neuinstallation des CheckMK-Agenten, z.B. nach Agenten-Problemen oder Version-Upgrades.

**Ziel-Hosts**: `all`

**Benutzer**: `tincadmin` (mit sudo-Rechten)

**Verwendete Rollen**:
- `checkmk.general.agent` (externe Collection)

**Wichtige Variablen**:

| Variable | Default | Beschreibung |
|----------|---------|-------------|
| `checkmk_agent_version` | `"2.4.0p17"` | Agent-Version |
| `checkmk_agent_edition` | `"cee"` | Edition (CEE = Commercial Enterprise Edition) |
| `checkmk_agent_server` | `servercow.observer` | CheckMK-Server |
| `checkmk_agent_site` | `"scowmon"` | Site-Name |
| `checkmk_agent_folder` | `"/managed_mailcows"` | Ziel-Ordner |
| `checkmk_agent_auto_activate` | `true` | Automatische Aktivierung |
| `checkmk_agent_tls` | `true` | TLS-Verschlüsselung aktivieren |
| `checkmk_agent_discover` | `true` | Automatische Service-Discovery |

**Verwendungsbeispiel**:

```bash
# Neuinstallation des Agenten auf allen Hosts
ansible-playbook playbooks/reinstall-cmk-agent.yml \
  -i inventories/icp-fra-pve1.yml \
  -K --ask-vault-pass

# Mit spezifischer Agent-Version
ansible-playbook playbooks/reinstall-cmk-agent.yml \
  -i inventories/icp-fra-pve1.yml \
  -e "checkmk_agent_version=2.4.0p20" \
  -K --ask-vault-pass

# Nur auf problematischen Hosts
ansible-playbook playbooks/reinstall-cmk-agent.yml \
  -i inventories/extern.yml \
  --limit mail-server-01.example.com \
  -K --ask-vault-pass
```

**Abhängigkeiten**:
- Vault-Datei mit CheckMK-Zugangsdaten (`checkmk_agent_user`, `checkmk_agent_pass`)
- Externe Collection `checkmk.general`
- CheckMK-Server muss erreichbar sein
- Host muss bereits im CheckMK registriert sein

**Besonderheiten**:
- **Strategie: linear** - Hosts werden nacheinander bearbeitet
- **Host-Auto-Discovery** aktiviert (`checkmk_agent_discover: true`)
- **Automatische API-Aktivierung** nach Host-Hinzufügen
- **IP-Adresse** wird automatisch aus `ansible_default_ipv4.address` extrahiert
- **Discovery mit Parallelisierung**: `max_parallel_tasks: 2`

**Workflow**:
1. Lädt Vault-Datei
2. Deinstalliert alten Agent (falls vorhanden)
3. Lädt neue Agent-Version herunter
4. Installiert neuen Agenten
5. Registriert Agent beim CheckMK-Server
6. Führt Service-Discovery durch
7. Aktiviert Änderungen

**⚠️ Hinweis**: Dieses Playbook verwendet eine ältere Agent-Version (2.4.0p17) als das Standard-Setup (2.3.0p34 in `group_vars/all.yml`). Passen Sie die Version bei Bedarf an.

---

## Rollen

### Rolle: checkmk-monitoring

**Zweck**: Integriert Hosts mit dem CheckMK-Überwachungsserver und verwaltet Monitoring-Agenten.

**Pfad**: `roles/checkmk-monitoring/`

**Hauptaufgaben**:

#### 1. create-host.yaml
Registriert neue Hosts auf dem CheckMK-Server.

- Verwendet CheckMK REST-API
- Erstellt Host-Eintrag mit IPv6-Adressen
- Setzt Host-Attribute (Ordner, Tags, IP-Adresse)
- Delegiert zu localhost (API-Aufruf)

**Beispiel-Verwendung**:
```yaml
- import_role:
    name: checkmk-monitoring
    tasks_from: create-host.yaml
```

#### 2. sign-bake-agents.yaml
Signiert und bäckt ausstehende Agent-Jobs im CheckMK.

- Signiert TLS-Agent-Zertifikate
- Bäckt Agent-Pakete
- Wartet auf Abschluss des Baking-Prozesses
- **Retry-Logik**: Versucht mehrfach bei Fehlern

**Beispiel-Verwendung**:
```yaml
- import_role:
    name: checkmk-monitoring
    tasks_from: sign-bake-agents.yaml
```

#### 3. discover-host.yaml
Führt automatische Service-Discovery auf Hosts durch.

- Scannt Host nach verfügbaren Services
- Fügt erkannte Services zum Monitoring hinzu
- Aktiviert Änderungen automatisch
- Delegiert zu localhost (API-Aufruf)

**Beispiel-Verwendung**:
```yaml
- import_role:
    name: checkmk-monitoring
    tasks_from: discover-host.yaml
```

#### 4. delete-host.yaml
Löscht Hosts vom CheckMK-Server.

- Entfernt Host aus Monitoring
- Bereinigt alle assoziierten Services
- Nützlich für Dekommissionierung

**Beispiel-Verwendung**:
```yaml
- import_role:
    name: checkmk-monitoring
    tasks_from: delete-host.yaml
```

#### 5. cleanup-agent-plugins.yaml
Bereinigt nicht benötigte Agent-Plugins auf überwachten Hosts.

- Entfernt veraltete oder unerwünschte Plugins
- Reduziert Overhead auf Agenten
- Verwendet Variable `checkmk_agent_plugins_to_remove`

**Beispiel-Verwendung**:
```yaml
- import_role:
    name: checkmk-monitoring
    tasks_from: cleanup-agent-plugins.yaml
```

**Standardvariablen** (`defaults/main.yaml`):

| Variable | Default | Beschreibung |
|----------|---------|-------------|
| `checkmk_agent_plugins_to_remove` | `["docker-mailq-monitoring"]` | Liste zu entfernender Plugins |

**Handler**:

| Handler | Funktion |
|---------|----------|
| `Activate Changes` | Aktiviert Konfigurationsänderungen auf CheckMK |
| `Sign and bake pending agent jobs` | Signiert Agent-Zertifikate mit Retry-Logik |

**Abhängigkeiten**:
- Keine lokalen Abhängigkeiten
- Externe Collection: `checkmk.general` erforderlich

**Verwendung in Playbooks**:

Das Playbook `setup-checkmk-monitoring.yml` zeigt die typische Verwendung:

```yaml
- name: Create host in CheckMK
  import_role:
    name: checkmk-monitoring
    tasks_from: create-host.yaml

- name: Sign and bake pending agent jobs
  import_role:
    name: checkmk-monitoring
    tasks_from: sign-bake-agents.yaml

- name: Install CheckMK agent
  include_role:
    name: checkmk.general.agent

- name: Wait for agent to be ready
  pause:
    minutes: 2

- name: Discover host
  import_role:
    name: checkmk-monitoring
    tasks_from: discover-host.yaml
```

---

## CheckMK-Konfiguration

### Global Variables (aus group_vars/all.yml)

```yaml
# CheckMK Agent Configuration
checkmk_agent_version: "2.3.0p34"
checkmk_agent_edition: "cee"
checkmk_agent_server: "servercow.observer"
checkmk_agent_site: "scowmon"
checkmk_agent_folder: "/managed_mailcows"
checkmk_agent_auto_activate: true
checkmk_agent_tls: true
checkmk_agent_discover: true
checkmk_agent_registration_mode: "automatic"
```

### Vault-Variablen (vault.yml)

```yaml
# Nicht sichtbar - verschlüsselt
checkmk_automation_user: "automation"
checkmk_automation_secret: "<verschlüsselt>"
checkmk_agent_user: "automation"
checkmk_agent_pass: "<verschlüsselt>"
```

---

## Best Practices

### 1. Monitoring neuer Hosts

Verwenden Sie `setup-checkmk-monitoring.yml` für neue Hosts. Es führt alle notwendigen Schritte automatisch durch.

### 2. Agent-Updates

Für bestehende Hosts mit alten Agent-Versionen:
```bash
ansible-playbook playbooks/reinstall-cmk-agent.yml \
  -i inventories/icp-fra-pve1.yml \
  -e "checkmk_agent_version=2.4.0p20" \
  -K --ask-vault-pass
```

### 3. Service-Discovery

CheckMK führt automatisch Discovery durch. Für manuelle Discovery nur bei Änderungen:
```bash
# Führen Sie setup-checkmk-monitoring.yml mit --limit aus
ansible-playbook playbooks/setup-checkmk-monitoring.yml \
  -i inventories/icp-fra-pve1.yml \
  --limit changed-host.example.com \
  -K --ask-vault-pass
```

### 4. Plugin-Bereinigung

Entfernen Sie regelmäßig nicht benötigte Plugins:
```bash
ansible-playbook playbooks/cleanups/cleanup-cmk-agent-plugins.yml \
  -i inventories/icp-fra-pve1.yml \
  -K
```

### 5. TLS-Verschlüsselung

Halten Sie `checkmk_agent_tls: true` für sichere Agent-Verbindungen.

---

## Fehlerbehebung

### Problem: Agent-Registrierung schlägt fehl

**Symptome**: Agent kann sich nicht beim Server registrieren

**Lösung**:
1. Überprüfen Sie Vault-Zugangsdaten
2. Testen Sie Erreichbarkeit des CheckMK-Servers:
   ```bash
   curl https://servercow.observer/scowmon
   ```
3. Überprüfen Sie Firewall-Regeln (Port 6556 für Agent-Communication)

### Problem: Service-Discovery findet keine Services

**Symptome**: Nach Installation werden keine Services erkannt

**Lösung**:
1. Warten Sie 2-3 Minuten nach Agent-Installation
2. Überprüfen Sie Agent-Status auf Host:
   ```bash
   systemctl status check-mk-agent.socket
   cmk-agent-ctl status
   ```
3. Manuelle Discovery im CheckMK-Web-Interface durchführen

### Problem: TLS-Zertifikat-Fehler

**Symptome**: Agent-Verbindung schlägt mit TLS-Fehler fehl

**Lösung**:
1. Regenerieren Sie Agent-Zertifikate:
   ```bash
   ansible-playbook playbooks/setup-checkmk-monitoring.yml \
     --tags sign-bake \
     -i inventories/... \
     -K --ask-vault-pass
   ```
2. Deinstallieren und neu installieren Sie den Agenten

### Problem: Alte Plugins stören Monitoring

**Symptome**: Fehler in Service-Checks oder hohe Agent-Last

**Lösung**:
```bash
# Bereinigen Sie Plugins
ansible-playbook playbooks/cleanups/cleanup-cmk-agent-plugins.yml \
  -i inventories/icp-fra-pve1.yml \
  -K

# Passen Sie checkmk_agent_plugins_to_remove in defaults/main.yaml an
```

---

## Externe Abhängigkeiten

### CheckMK Collection Installation

Installieren Sie die erforderliche Collection:

```bash
ansible-galaxy collection install checkmk.general
```

Oder mit spezifischer Version:

```bash
ansible-galaxy collection install checkmk.general:5.0.0
```

### Dokumentation

Offizielle CheckMK Collection Dokumentation:
- https://docs.checkmk.com/stable/en/agent_linux.html
- https://galaxy.ansible.com/checkmk/general

---

**Navigation**: [← Zurück: OS-Management](01-OS-Management.md) | [Nächstes: Container-Management →](03-Container-Management.md)