Playbooks

Playbooks sind mehrstufige Workflows, die mehrere Scripts und Tasks nacheinander auf Hosts ausfuehren. Typischer Anwendungsfall: Wartungsfenster mit Snapshot, Update, Reboot und Health-Check als aufeinanderfolgende Schritte.

Konzept

Ein Playbook besteht aus:

1. Definition - Name, Beschreibung und Ziel-Modul
2. Steps - Geordnete Liste von Aktionen (Script, Task oder Wartezeit)
3. Fehlerbehandlung - Pro Step konfigurierbar (Abbrechen oder Weiter)

Step-Typen

Typ	Beschreibung	Konfiguration
Script	Ein Script aus der Bibliothek ausfuehren	Script-Auswahl, optionaler Timeout
Task	Systemaufgabe ausfuehren (Update, Reboot, etc.)	Task-Typ + Parameter
Wartezeit	Pause zwischen Steps	Dauer in Sekunden
Wake on LAN	Magic Packet an einen Host senden	Automatische MAC + Proxy-Erkennung
Online pruefen	Warten bis ein Host online ist	Timeout + Poll-Intervall
VM Snapshot	PVE-Snapshot einer VM erstellen	VMID + Snapshot-Name
Webhook	HTTP-Request an eine URL senden	URL, Methode, Body, Headers

Fehlerbehandlung (On-Error)

Fuer jeden Step kann festgelegt werden, was bei einem Fehler passiert:

Option	Verhalten
stop	Playbook wird sofort gestoppt (Standard)
continue	Naechster Step wird trotz Fehler ausgefuehrt

Timeout pro Step

Jeder Step kann einen individuellen Timeout haben (Standard: 300 Sekunden). Wird der Timeout ueberschritten, gilt der Step als fehlgeschlagen und die konfigurierte Fehlerbehandlung greift.

Verfuegbare Task-Typen

Die folgenden Task-Typen stehen fuer Playbook-Steps vom Typ "Task" zur Verfuegung:

Allgemein (alle Module)

Task-Typ	Beschreibung
AGENT_UPDATE	Agent auf die neueste Version aktualisieren
RUN_SCRIPT	Ein Script aus der Bibliothek ausfuehren
REBOOT	System neustarten

OPNsense

Task-Typ	Beschreibung
system_update	OPNsense-Firmware-Update
update_reboot	Firmware-Update mit Neustart
OPN_REBOOT	OPNsense neustarten
OPN_UPGRADE_CHECK	Major-Upgrade-Verfuegbarkeit pruefen
OPN_MAJOR_UPGRADE	Major-Upgrade durchfuehren
BACKUP	Konfigurations-Backup erstellen
SYNC_CONFIG	HA-Konfiguration synchronisieren

Proxmox VE

Task-Typ	Beschreibung
PVE_UPDATE	Paket-Update (apt dist-upgrade)
PVE_REBOOT	PVE-Host neustarten
PVE_UPGRADE_CHECK	Major-Upgrade-Verfuegbarkeit pruefen
PVE_MAJOR_UPGRADE	Major-Upgrade durchfuehren
PVE_VM_START	VM starten
PVE_VM_STOP	VM stoppen (hart)
PVE_VM_SHUTDOWN	VM herunterfahren (ACPI)
PVE_VM_REBOOT	VM neustarten
PVE_SNAPSHOT	VM-Snapshot erstellen
PVE_SNAPSHOT_DELETE	VM-Snapshot loeschen

Proxmox Backup Server

Task-Typ	Beschreibung
PBS_UPDATE	Paket-Update (apt dist-upgrade)
PBS_REBOOT	PBS-Host neustarten
PBS_UPGRADE_CHECK	Major-Upgrade-Verfuegbarkeit pruefen
PBS_MAJOR_UPGRADE	Major-Upgrade durchfuehren
PBS_GC	Garbage Collection auf Datastore
PBS_VERIFY	Backup-Integritaet pruefen
PBS_PRUNE	Alte Backups bereinigen
PBS_SYNC	Datastore synchronisieren

Linux

Task-Typ	Beschreibung
LINUX_UPDATE	Paket-Update (apt upgrade / dnf upgrade)

Windows

Task-Typ	Beschreibung
WINDOWS_UPDATE	Windows Updates installieren

Webhook Step

Der Step-Typ Webhook sendet einen HTTP-Request an eine beliebige URL. Damit koennen externe Systeme wie DATAZONE Connect, Slack, Teams oder andere REST-APIs angesteuert werden.

Feld	Beschreibung	Standard
URL	Ziel-URL des HTTP-Requests	-
Methode	HTTP-Methode (GET, POST, PUT, DELETE)	POST
Body	Request-Body (JSON) mit Platzhaltern	-
Headers	HTTP-Headers (z.B. Content-Type)	-
Timeout	Maximale Wartezeit in Sekunden	30s
Success Codes	Erwartete HTTP-Statuscodes	2xx

Variablen-Platzhalter

Im Body und in der URL koennen folgende Platzhalter verwendet werden, die automatisch mit den Daten des aktuellen Hosts ersetzt werden:

Platzhalter	Beschreibung
{hostname}	Hostname des Ziel-Hosts
{ip}	IP-Adresse des Hosts
{module}	Modultyp (linux, windows, opnsense, etc.)
{host_id}	Host-ID in DATAZONE Control
{customer_name}	Kundenname
{customer_number}	Kundennummer
{playbook_name}	Name des Playbooks
{step_number}	Aktuelle Step-Nummer
{date}	Aktuelles Datum (YYYY-MM-DD)

Connect-Integration

Webhook-Steps eignen sich ideal fuer die Anbindung an DATAZONE Connect. Damit koennen z.B. automatisch Taetigkeitsnachweise in Nuclos erstellt oder Teams-Benachrichtigungen gesendet werden.

Playbooks verwalten

Die Playbook-Verwaltung erreichen Sie ueber den Navigationspunkt Playbooks.

Playbook erstellen

1. Klicken Sie auf Playbook erstellen
2. Konfigurieren Sie das Playbook:

Feld	Beschreibung
Name	Eindeutiger Name des Playbooks
Beschreibung	Zweck und Ablauf
Modul	Fuer welches Modul (oder alle)
Aktiv	Ob das Playbook ausfuehrbar ist

Steps konfigurieren

Im Step-Editor koennen Sie Steps hinzufuegen, bearbeiten und per Drag-and-Drop umsortieren:

1. Klicken Sie auf Step hinzufuegen
2. Waehlen Sie den Step-Typ (Script / Task / Wartezeit)
3. Konfigurieren Sie den Step:
   • Script: Waehlen Sie ein Script aus der Bibliothek (gefiltert nach Playbook-Modul)
   • Task: Waehlen Sie einen Task-Typ aus der Liste (siehe oben)
   • Wartezeit: Geben Sie die Pause in Sekunden ein
4. Legen Sie das Fehlerverhalten fest (stop / continue)
5. Optional: Timeout pro Step definieren (Standard: 300 Sekunden)

Reihenfolge aendern

Steps koennen per Drag-and-Drop oder ueber die Pfeil-Buttons umsortiert werden. Die Step-Nummern werden automatisch angepasst.

Abweichendes Ziel (Per-Step Target)

Standardmaessig werden alle Steps auf dem Host ausgefuehrt, fuer den das Playbook gestartet wurde. Mit der Option Abweichendes Ziel kann ein Step auf einem anderen Host oder sogar einem anderen Modul ausgefuehrt werden.

Das ist besonders nuetzlich fuer Cross-Module-Workflows:

• WoL an einen Windows-Host senden, der auf dem PVE-Host als VM laeuft
• Snapshot auf dem PVE-Host erstellen, bevor der Windows-Host aktualisiert wird
• Online pruefen eines anderen Hosts nach dem WoL-Paket

Aktivieren Sie die Checkbox Abweichendes Ziel im Step-Editor, um Modul und Host zu waehlen.

VM Snapshot Step

Der Step-Typ VM Snapshot erstellt einen Snapshot einer virtuellen Maschine auf einem PVE-Host:

Feld	Beschreibung
VMID	ID der virtuellen Maschine (z.B. 100)
Snapshot-Name	Name des Snapshots, {date} wird durch Datum ersetzt
RAM einbeziehen	VM-Speicher in den Snapshot einbeziehen

Platzhalter

Der Snapshot-Name unterstuetzt den Platzhalter {date}, der automatisch durch das aktuelle Datum im Format YYYYMMDD-HHMMSS ersetzt wird. Beispiel: playbook-{date} wird zu playbook-20260213-030000.

Online-Pruefung Step

Der Step-Typ Online pruefen wartet, bis ein Host online ist (z.B. nach einem WoL-Paket oder Reboot):

Feld	Beschreibung	Standard
Timeout	Maximale Wartezeit in Sekunden	300s

Der Step prueft alle 10 Sekunden, ob der Host erreichbar ist. Wenn der Timeout ablaeuft, wird der konfigurierte Fehlerbehandlungsmodus angewendet.

Playbook ausfuehren

Ueber die Playbook-Verwaltung

1. Oeffnen Sie das Playbook in der Liste
2. Klicken Sie auf Ausfuehren
3. Waehlen Sie das Ziel-Modul und die Hosts
4. Bestaetigen Sie die Ausfuehrung

Ueber das Kontextmenue

1. Rechtsklick auf einen Host in der Host-Tabelle
2. Waehlen Sie Playbook ausfuehren
3. Waehlen Sie das gewuenschte Playbook aus dem Untermenue

Ueber Zeitplaene (Jobs)

Playbooks koennen als geplante Aktion in Update-Zeitplaenen konfiguriert werden:

1. Erstellen Sie einen neuen Job unter Jobs
2. Waehlen Sie als Aktionstyp Playbook
3. Waehlen Sie das Playbook aus der Dropdown-Liste
4. Konfigurieren Sie Zeitplan und Ziel-Hosts

Ausfuehrung ueberwachen

Laufende Ausfuehrungen

Unter Playbooks > Tab Ausfuehrungen sehen Sie alle laufenden und abgeschlossenen Ausfuehrungen:

Spalte	Beschreibung
Playbook	Name des ausgefuehrten Playbooks
Host	Ziel-Host
Status	Running, Success, Failed oder Stopped
Aktueller Step	Welcher Step gerade ausgefuehrt wird
Fortschritt	Visueller Fortschrittsbalken
Gestartet	Startzeit der Ausfuehrung

Step-Ergebnisse

Klicken Sie auf eine Ausfuehrung, um die Detail-Ansicht zu oeffnen:

• Jeder Step wird mit Status-Badge angezeigt (Erfolg / Fehler / Laufend / Uebersprungen)
• Ausgabe und Dauer pro Step
• Bei Fehlern: Welche On-Error-Aktion ausgefuehrt wurde

Ausfuehrung stoppen

Laufende Ausfuehrungen koennen jederzeit gestoppt werden:

1. Oeffnen Sie die Ausfuehrung
2. Klicken Sie auf Stoppen
3. Der aktuelle Step wird noch abgeschlossen, danach stoppt das Playbook

Beispiele

PVE Wartungsfenster

Ein typisches Playbook fuer Proxmox VE Wartung:

Step	Typ	Aktion	Bei Fehler	Timeout
1	Script	VM Snapshots erstellen	stop	600s
2	Task	PVE_UPDATE	continue	1800s
3	Wartezeit	30 Sekunden warten	-	-
4	Script	Health-Check	continue	120s
5	Task	PVE_REBOOT	stop	300s
6	Script	Benachrichtigung senden	continue	60s

Windows Update mit PVE-Snapshot-Absicherung

Ein Cross-Module-Playbook: Windows-Host aufwecken, absichern und aktualisieren:

Step	Typ	Ziel	Aktion	Bei Fehler
1	Wake on LAN	Windows-Host	Host aufwecken	stop
2	Online pruefen	Windows-Host	Warten bis online (max 5 Min)	stop
3	VM Snapshot	PVE-Host	Snapshot von VM 100	stop
4	Task	Windows-Host	Windows Update	continue
5	Online pruefen	Windows-Host	Warten auf Reboot (max 10 Min)	continue

Cross-Module

In diesem Beispiel wird das Playbook auf den Windows-Host gestartet. Steps 3 nutzt Abweichendes Ziel, um den Snapshot auf dem PVE-Host zu erstellen, auf dem die VM laeuft.

Best Practices

• Snapshots zuerst: Erstellen Sie vor kritischen Aenderungen immer einen Snapshot
• Health-Checks einbauen: Pruefen Sie nach Updates, ob das System ordnungsgemaess funktioniert
• Online-Pruefung nach WoL: Nutzen Sie den check_online Step nach Wake-on-LAN
• Benachrichtigungen: Nutzen Sie den letzten Step fuer Statusmeldungen
• Timeouts: Setzen Sie angemessene Timeouts, um haengende Steps zu erkennen
• Fehlerbehandlung: Nutzen Sie continue fuer unkritische Steps und stop fuer kritische