claude_settings/plans/silly-waddling-dragonfly.md

Plan: VMware-Alarme mit VM-Namen in Zabbix anzeigen

Problem

Die Operational Data bei VMware-Alarm-Triggern zeigt alarm-127.group-d1 (interner vSphere-Key) statt des VM-Namens. Man sieht nicht, WELCHE VM ein Problem hat.

Ursache

• vmware.alarms.get[url] sammelt Alarme auf Datacenter-Ebene (entity group-d1 = Root)
• Das Alarm-JSON enthält kein Entity-/VM-Name-Feld
• Der Trigger-Prototype hat leere opdata → Zabbix zeigt den lastvalue (= den nutzlosen Key)
• Das VMware Guest Template hat keine Alarm-Discovery (auch nicht in der neusten Version 7.4-1 auf GitHub)

Lösung: Per-VM Alarm-Discovery zum VMware Guest Template hinzufügen

vmware.vm.alarms.get[url, uuid] existiert als Item-Key in Zabbix 7.0 — wird nur nicht im Template verwendet. Wenn wir Alarm-Discovery auf die VMware Guest Hosts bringen, erscheinen Alarm-Trigger direkt auf dem jeweiligen VM-Host. Der Host-Name im Dashboard IST der VM-Name → Problem gelöst.

Warum das funktioniert

vSphere feuert Alarme auf zwei Ebenen:

1. Datacenter-Level: Gesamtstatus ("irgendwo gibt es ein Backup-Problem") → aktueller Zustand
2. Entity-Level (VM/Host): Alarm auf der spezifischen VM die das Problem hat → was wir brauchen

vmware.vm.alarms.get liefert die Entity-Level Alarme pro VM.

Schritte

Schritt 0: Template-Backup (PFLICHT, VOR jeder Änderung)

Vollständige Exports beider VMware-Templates via Zabbix API als JSON-Backup. Enthält ALLE Objekte: Items, Triggers, Discovery Rules, Item-/Trigger-Prototypen, Tags, Preprocessing, Macros, Dependencies.

a) VMware Guest Template (10174) — wird geändert:

configuration.export format=json options.templates=[10174]
→ ~/Nextcloud/vinos/zabbix/backups/vmware-guest-template-10174-backup.json

b) VMware Template (10173) — opdata-Änderung:

configuration.export format=json options.templates=[10173]
→ ~/Nextcloud/vinos/zabbix/backups/vmware-template-10173-backup.json

c) Verifizierung der Backups:

• Dateigröße prüfen (sollte mehrere KB sein)
• JSON-Validität prüfen (python3 -m json.tool)
• Stichprobe: Tags im Backup vorhanden? (grep nach "tags")
• Stichprobe: Trigger-Prototypen im Backup? (grep nach "trigger_prototypes")

Restore bei Problemen:

configuration.import format=json source=[Dateiinhalt] rules.templates.updateExisting=true

Backups werden ins Git committed (zabbix/backups/) damit sie versioniert und jederzeit wiederherstellbar sind.

Schritt 1: Quick-Fix — opdata auf bestehendem Trigger-Prototype verbessern

Template-Ebene (VMware Template ID 10173):

• Trigger-Prototype ID 54450 → opdata setzen auf {#VMWARE.ALARMS.STATUS}
• Zeigt dann "red"/"yellow" statt "alarm-127.group-d1"
• Betrifft alle 5 entdeckten Alarme auf srv-nu-vcenter01

API-Call:

triggerprototype.update: triggerid=54450, opdata="{#VMWARE.ALARMS.STATUS}"

Schritt 2: Validierung — Per-VM Alarme testen

Bevor wir das Template ändern, prüfen ob vmware.vm.alarms.get pro VM funktioniert:

1. Temporäres Test-Item auf einer VM erstellen (z.B. SRV-DATA01, Host-ID 10893):
   • Key: vmware.vm.alarms.get[{$VMWARE.URL},{$VMWARE.VM.UUID}]
   • Type: Simple Check
   • Value Type: Text
   • History: 1h
2. Warten bis Daten kommen (1-2 Min)
3. Prüfen ob der Backup-Alarm in den per-VM Daten auftaucht
4. Test-Item wieder löschen

Mögliche Ergebnisse:

• JSON enthält den Alarm → weiter mit Schritt 3
• JSON ist leer → Backup-Alarm feuert nur auf Datacenter-Ebene, Schritt 3 bringt für diesen speziellen Alarm nichts

Schritt 3: Neues Template "VMware Guest Alarms" erstellen (PARALLEL, nicht am Original)

Strategie: Statt das Original-Template (10174) zu modifizieren, erstellen wir ein separates Template mit nur der Alarm-Discovery. Dieses wird zusätzlich zu "VMware Guest" auf die VM-Hosts gelinkt.

Vorteile:

• Original "VMware Guest" bleibt 100% unverändert
• Bei Problemen: Template unlinken → alle Alarm-Items sofort weg
• Nachbesserungen am neuen Template ohne Risiko
• Bei Zabbix-Update wird das Original-Template aktualisiert, unser Custom-Template bleibt

Template-Name: VMware Guest Alarms Host Group: Gleiche wie VMware Guest (wird beim Linken automatisch zugewiesen)

a) Template erstellen:

template.create:
  host: "VMware Guest Alarms"
  name: "VMware Guest Alarms"
  description: "Per-VM Alarm-Discovery für VMware Guest Hosts.
                Ergänzt das Standard VMware Guest Template um Alarm-Monitoring.
                Benötigt Macros {$VMWARE.URL} und {$VMWARE.VM.UUID} vom VMware Guest Template."
  groups: [{groupid: <Templates-Gruppe>}]

b) Master-Item (Simple Check):

item.create:
  hostid: [neues Template]
  name: "Get VM alarms"
  key: vmware.vm.alarms.get[{$VMWARE.URL},{$VMWARE.VM.UUID}]
  type: Simple Check (3)
  value_type: Text (4)
  history: 0
  delay: 0 (VMware Collector)

c) Discovery Rule (Dependent):

discoveryrule.create:
  hostid: [neues Template]
  name: "VMware VM alarm discovery"
  key: vmware.vm.alarms.discovery
  type: Dependent (18)
  master_itemid: [Get VM alarms Item]
  lifetime: 0
  LLD Macro Paths:
    {#VMWARE.ALARMS.DESC} → $.description
    {#VMWARE.ALARMS.KEY} → $.key
    {#VMWARE.ALARMS.NAME} → $.name
    {#VMWARE.ALARMS.STATUS} → $.overall_status

d) Item-Prototype (Dependent):

itemprototype.create:
  ruleid: [Discovery Rule]
  hostid: [neues Template]
  name: "{#VMWARE.ALARMS.NAME}"
  key: vmware.vm.alarms.status["{#VMWARE.ALARMS.KEY}"]
  type: Dependent (18)
  master_itemid: [Get VM alarms Item]
  value_type: Character (1)
  preprocessing:
    1. JSONPath: $.[?(@.key == "{#VMWARE.ALARMS.KEY}")].key.first()
       error_handler: set value to -1
    2. Throttling: 1h

e) Trigger-Prototype:

triggerprototype.create:
  description: "VMware VM: {#VMWARE.ALARMS.NAME}"   ← "VM:" um von vCenter-Level zu unterscheiden
  expression: last(/VMware Guest Alarms/vmware.vm.alarms.status["{#VMWARE.ALARMS.KEY}"])<>-1
  opdata: "{#VMWARE.ALARMS.STATUS}"
  priority: 0 (Not classified) ← gleich wie vCenter-Level Trigger
  comments: "{#VMWARE.ALARMS.DESC}"
  tags: [{"tag": "scope", "value": "notice"}]

Tag-Kontext: Das Notification-System basiert auf Tags wie Meldung_Webhook_* / Meldung_Mail_* (siehe notifications.md). Der scope=notice Tag kommt vom Template. Spezifische Routing-Tags (Meldung_*) werden bei Bedarf nachträglich auf entdeckte Trigger gesetzt — nicht auf dem Prototype.

Schritt 3b: Template auf VMware Guest Hosts linken

Erst auf einem Test-Host:

1. Template "VMware Guest Alarms" auf SRV-DATA01 (10893) linken
2. Warten bis Master-Item Daten liefert (~1-2 Min)
3. LLD abwarten (~5-10 Min)
4. Prüfen ob Alarm-Items erstellt werden

Bei Erfolg auf alle VMware Guest Hosts:

• host.get mit templateids=[10174] → Liste aller VMware Guest Hosts
• host.massupdate mit templates: bestehende + neues Template

Schritt 4: Verifizierung

1. Warten bis LLD auf VMware Guest Hosts läuft (~5-10 Min)
2. Prüfen ob per-VM Alarm-Items erstellt werden
3. Prüfen ob der Backup-Alarm auf der betroffenen VM auftaucht
4. Dashboard-Anzeige prüfen: VM-Name sollte in Host-Spalte stehen

Schritt 5: Aufräumen

• History am Master-Item vmware.alarms.get auf vCenter (120476) zurück auf 0 setzen
• Ggf. den Datacenter-Level Alarm-Trigger deaktivieren oder behalten (als Fallback)

Schritt 6: Dokumentation + Commits

• zabbix/README.md: VMware Alarm-Monitoring Pattern dokumentieren
• zabbix/copilot-instructions.md: Pitfall dokumentieren (opdata leer = zeigt lastvalue)
• Infrastructure: Falls relevant
• Commits in zabbix-Repo + pushen

Risiken & Fallbacks

Risiko	Auswirkung	Fallback
vmware.vm.alarms.get liefert keine per-VM Alarme	Backup-Alarm nur auf Datacenter-Ebene	opdata-Fix (Schritt 1) ist trotzdem besser als Status quo
Viele neue Items pro VM	Mehr Last auf Zabbix-Server	Items haben 1h Throttling, Master-Item hat delay=0 (VMware Collector Intervall)
Neues Template funktioniert nicht wie erwartet	Falsches/kein Discovery	Template unlinken → alle Items/Trigger sofort weg, kein Restrisiko

Rollback-Strategie

1. Per-VM Alarms funktionieren nicht: Template "VMware Guest Alarms" von Hosts unlinken → fertig
2. opdata-Änderung problematisch: triggerprototype.update opdata zurück auf "" → LLD re-run
3. Komplett-Rollback: Template-Backup importieren via configuration.import

Betroffene Dateien/Objekte

Was	ID	Aktion
VMware Template Trigger-Prototype	54450	opdata setzen
NEUES Template "VMware Guest Alarms"	(wird erstellt)	Alarm-Discovery für VMs
VMware Guest Template	10174	NICHT geändert (nur Backup)
Master-Item vCenter (temporär)	120476	History zurück auf 0
zabbix/README.md	—	Doku ergänzen

Verifizierung

# Nach Schritt 2: Test-Item prüfen
item.get hostids=[10893] search={"key_": "vm.alarms"}
history.get itemids=[TEST_ITEM_ID] history=4

# Nach Schritt 3: Per-VM Alarm Discovery prüfen
item.get templateids=[10174] search={"key_": "alarm"}
# Auf einem VMware Guest Host:
item.get hostids=[10893] search={"key_": "alarm"}
trigger.get hostids=[10893] search={"description": "Backup"}