operating-automation/docs/02-Monitoring.md

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:

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

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

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

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

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

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

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

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

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

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

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:

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

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:

   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:

   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:

   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:

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

ansible-galaxy collection install checkmk.general

Oder mit spezifischer Version:

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 | Nächstes: Container-Management →