add docs
This commit is contained in:
Ansible Servercow
454
docs/02-Monitoring.md
Normal file
454
docs/02-Monitoring.md
Normal file
@@ -0,0 +1,454 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user