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

```bash
# 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"}
```