operating-automation/docs/06-Virtualisierung.md

# Virtualisierung (Proxmox)

## Übersicht

Diese Kategorie umfasst die Rolle zur Proxmox VE-Automatisierung, insbesondere für VM-Snapshot-Verwaltung. Die Proxmox-Integration wird von vielen anderen Playbooks genutzt, um Snapshots vor kritischen Operationen zu erstellen.

**Anwendungsfälle**:
- Automatische Snapshot-Erstellung vor OS-Updates
- Automatische Snapshot-Erstellung vor Mailcow-Updates
- Snapshot-Bereinigung nach erfolgreichen Updates
- Rollback-Möglichkeit bei fehlgeschlagenen Operationen
- VM-ID-Ermittlung für API-Operationen

**Proxmox-Cluster**: `icp-fra-pve1` (6 Hosts)

---

## Verwendung in anderen Playbooks

Die Proxmox-Automation-Rolle wird nicht direkt über dedizierte Playbooks aufgerufen, sondern als **integraler Bestandteil** anderer Playbooks verwendet:

### Playbooks mit Proxmox-Integration

| Playbook | Verwendung | Snapshot-Name-Muster |
|----------|------------|----------------------|
| [`os-update.yml`](01-OS-Management.md#os-updateyml) | Snapshot vor OS-Updates | `AUTO_before_os_update_{{ date }}` |
| [`os-major-upgrade.yml`](01-OS-Management.md#os-major-upgradeyml) | Snapshot vor Major-Upgrade | `AUTO_before_major_{{ date }}` |
| [`update-mailcow.yaml`](04-Mail-Server-Verwaltung.md#update-mailcowyaml) | Snapshot vor Mailcow-Update | `pre-mailcow-update-{{ version }}` |
| `cleanups/clean-pve-snapshots.yml` | Snapshot-Löschung | Alle außer "current" |

### Beispiel-Integration in Playbook

```yaml
- name: OS-Update mit Snapshot
  hosts: all
  become: true
  
  pre_tasks:
    - name: Load vault
      include_vars: ../vault.yml
      when: do_snapshots | bool
  
  tasks:
    - name: Get Proxmox VM ID
      include_role:
        name: proxmox-automation
        tasks_from: get-vmid
      when: do_snapshots | bool
    
    - name: Create pre-update snapshot
      include_role:
        name: proxmox-automation
        tasks_from: create-snapshots
      vars:
        snapshot_name: "AUTO_before_update_{{ ansible_date_time.date }}"
      when: do_snapshots | bool
    
    # ... Update-Tasks ...
```

---

## Rollen

### Rolle: proxmox-automation

**Zweck**: Automatisiert Proxmox VE VM-Verwaltung, primär für Snapshot-Operationen.

**Pfad**: `roles/proxmox-automation/`

**Hauptaufgaben**:

#### 1. get-vmid.yaml

Ermittelt die Proxmox VM-ID für den aktuellen Host.

**Funktionen**:
- Verwendet Proxmox API zur VM-ID-Ermittlung
- Sucht nach VM mit passendem Hostname
- Setzt `proxmox_vmid` Fact für weitere Operationen
- Delegiert zu localhost (API-Aufruf)

**Benötigte Variablen**:
```yaml
proxmox_host: "pve-cluster.example.com"
proxmox_user: "automation@pve"
proxmox_token_id: "ansible"
proxmox_token_secret: "<aus Vault>"
```

**Verwendung**:
```yaml
- include_role:
    name: proxmox-automation
    tasks_from: get-vmid
```

**Output**:
```yaml
proxmox_vmid: 100  # VM-ID des aktuellen Hosts
```

**API-Endpunkt**: `GET /api2/json/cluster/resources?type=vm`

---

#### 2. create-snapshots.yaml

Erstellt VM-Snapshots mit automatischer Retention (behält letzten 2).

**Funktionen**:
- Erstellt benannten Snapshot der VM
- Löscht alte Snapshots automatisch
- **Retention**: Behält nur die letzten 2 Snapshots
- Wartet auf Snapshot-Completion
- Delegiert zu localhost (API-Aufruf)

**Benötigte Variablen**:
```yaml
snapshot_name: "pre-update-2026-04-14"
proxmox_vmid: 100  # Aus get-vmid Task
proxmox_host: "pve-cluster.example.com"
proxmox_user: "automation@pve"
proxmox_token_id: "ansible"
proxmox_token_secret: "<aus Vault>"
```

**Verwendung**:
```yaml
- include_role:
    name: proxmox-automation
    tasks_from: create-snapshots
  vars:
    snapshot_name: "my-snapshot-{{ ansible_date_time.date }}"
```

**Snapshot-Retention-Logik**:
1. Listet alle existierenden Snapshots auf
2. Sortiert nach Erstellungsdatum
3. Löscht alle außer den letzten 2
4. Erstellt neuen Snapshot
5. Wartet auf Completion

**API-Endpunkte**:
- `GET /api2/json/nodes/{node}/qemu/{vmid}/snapshot`
- `POST /api2/json/nodes/{node}/qemu/{vmid}/snapshot`
- `DELETE /api2/json/nodes/{node}/qemu/{vmid}/snapshot/{snapname}`

**⚠️ Wichtig**: Die Retention von 2 Snapshots ist hardcoded. Ältere Snapshots werden **automatisch gelöscht**.

---

#### 3. delete-snapshots.yaml

Löscht alle Snapshots außer "current" (aktiver Zustand).

**Funktionen**:
- Listet alle Snapshots einer VM auf
- Löscht alle Snapshots außer "current"
- Useful für Cleanup nach erfolgreichen Updates
- Delegiert zu localhost (API-Aufruf)

**Benötigte Variablen**:
```yaml
proxmox_vmid: 100
proxmox_host: "pve-cluster.example.com"
proxmox_user: "automation@pve"
proxmox_token_id: "ansible"
proxmox_token_secret: "<aus Vault>"
```

**Verwendung**:
```yaml
- include_role:
    name: proxmox-automation
    tasks_from: delete-snapshots
```

**Workflow**:
1. Abruft alle Snapshots der VM
2. Filtert "current" aus (wird nicht gelöscht)
3. Iteriert über verbleibende Snapshots
4. Löscht jeden Snapshot
5. Wartet auf Completion

**API-Endpunkte**:
- `GET /api2/json/nodes/{node}/qemu/{vmid}/snapshot`
- `DELETE /api2/json/nodes/{node}/qemu/{vmid}/snapshot/{snapname}`

**Verwendung**: Siehe [Cleanup-Aufgaben → clean-pve-snapshots.yml](08-Cleanup-Aufgaben.md#clean-pve-snapshotsyml)

---

## Vault-Konfiguration

### Erforderliche Variablen in vault.yml

```yaml
# Proxmox API Credentials
proxmox_host: "pve-cluster.example.com"
proxmox_user: "automation@pve"
proxmox_token_id: "ansible"
proxmox_token_secret: "<generiertes API-Token>"
```

### Proxmox API-Token erstellen

1. **Login to Proxmox Web Interface**
2. **Datacenter → Permissions → API Tokens**
3. **Add API Token**:
   - User: `automation@pve` (erstellen falls nicht vorhanden)
   - Token ID: `ansible`
   - Privilege Separation: **Unchecked** (Token hat alle User-Rechte)
   - Expire: Nie oder lang genug
4. **Kopieren Sie den Secret** (nur einmal sichtbar!)
5. **Speichern Sie in vault.yml**

### Benötigte Proxmox-Berechtigungen

Der Automation-User benötigt folgende Berechtigungen:

| Pfad | Berechtigung | Zweck |
|------|--------------|-------|
| `/vms` | `VM.Snapshot` | Snapshots erstellen/löschen |
| `/vms` | `VM.Audit` | VM-Informationen lesen |
| `/` | `Sys.Audit` | Cluster-Ressourcen lesen |

**Minimale Berechtigung**:
```bash
# Via Proxmox CLI
pveum role add AutomationRole -privs "VM.Snapshot,VM.Audit,Sys.Audit"
pveum aclmod / -user automation@pve -role AutomationRole
```

---

## Externe Abhängigkeiten

### Community Proxmox Collection

**Installation**:
```bash
ansible-galaxy collection install community.proxmox:1.5.0
```

**In requirements.yml**:
```yaml
collections:
  - name: community.proxmox
    version: "1.5.0"
```

**Installation via requirements**:
```bash
ansible-galaxy collection install -r roles/proxmox-automation/requirements.yml
```

### Verwendete Module

- `community.general.proxmox_snap`: Snapshot-Verwaltung
- `community.general.proxmox`: VM-Informationen
- `ansible.builtin.uri`: Für direkte API-Aufrufe

**Dokumentation**:
- https://docs.ansible.com/ansible/latest/collections/community/general/proxmox_snap_module.html
- https://pve.proxmox.com/wiki/Proxmox_VE_API

---

## Best Practices

### 1. Snapshots nur bei kritischen Operationen

Aktivieren Sie Snapshots für:
- ✅ OS Major-Upgrades
- ✅ Mailcow-Updates (große Versionssprünge)
- ✅ Konfigurationsänderungen an kritischen Services
- ❌ Nicht für tägliche OS-Updates (außer bei kritischen Systemen)

```bash
# Mit Snapshots
ansible-playbook playbooks/os-major-upgrade.yml \
  -e "do_snapshots=true" \
  ...

# Ohne Snapshots (schneller, aber riskanter)
ansible-playbook playbooks/os-update.yml \
  -e "do_snapshots=false" \
  ...
```

### 2. Aussagekräftige Snapshot-Namen

Verwenden Sie beschreibende Namen:
```yaml
# Gut
snapshot_name: "pre-mailcow-update-2026-03b"
snapshot_name: "before-debian-trixie-upgrade"
snapshot_name: "AUTO_before_major_2026-04-14"

# Schlecht
snapshot_name: "snapshot1"
snapshot_name: "backup"
```

### 3. Regelmäßiges Snapshot-Cleanup

Bereinigen Sie alte Snapshots nach erfolgreichen Updates:
```bash
# Nach erfolgreichem Update
ansible-playbook playbooks/cleanups/clean-pve-snapshots.yml \
  -i inventories/icp-fra-pve1.yml \
  -K --ask-vault-pass
```

### 4. Snapshot-Retention beachten

Die Rolle behält automatisch nur die **letzten 2 Snapshots**. Planen Sie entsprechend:
- Tag 1: Snapshot A (vor Update 1)
- Tag 2: Snapshot B (vor Update 2) → Snapshot A bleibt
- Tag 3: Snapshot C (vor Update 3) → Snapshot A wird gelöscht, B bleibt

### 5. Storage-Kapazität überwachen

Snapshots benötigen Speicherplatz:
```bash
# Proxmox Storage-Nutzung prüfen
pvesm status

# Pro VM Snapshot-Größe
qm listsnapshot <vmid>
```

### 6. Snapshot-Limits beachten

Proxmox hat keine harte Snapshot-Anzahl-Begrenzung, aber:
- ⚠️ Zu viele Snapshots degradieren Performance
- ⚠️ Snapshots sind keine Backups (auf gleichem Storage)
- ✅ Maximale Empfehlung: 5-10 Snapshots pro VM

---

## Snapshot-Rollback

### Manuelle Rollback über Proxmox Web-Interface

1. **VM auswählen** in Proxmox
2. **Snapshots** Tab öffnen
3. **Gewünschten Snapshot auswählen**
4. **Rollback** klicken
5. **Bestätigen**

**⚠️ Warnung**: Rollback überschreibt aktuellen Zustand!

### Rollback via CLI (auf Proxmox-Host)

```bash
# Liste Snapshots
qm listsnapshot <vmid>

# Rollback zu Snapshot
qm rollback <vmid> <snapshot-name>

# Beispiel
qm rollback 100 pre-update-2026-04-14
```

### Rollback via Ansible (manuell)

```yaml
- name: Rollback to snapshot
  hosts: localhost
  tasks:
    - name: Proxmox Snapshot Rollback
      community.general.proxmox_snap:
        api_host: "{{ proxmox_host }}"
        api_user: "{{ proxmox_user }}"
        api_token_id: "{{ proxmox_token_id }}"
        api_token_secret: "{{ proxmox_token_secret }}"
        vmid: 100
        snapname: "pre-update-2026-04-14"
        state: rollback
```

**⚠️ Wichtig**: Nach Rollback ist die VM im Zustand des Snapshots. Alle Änderungen danach gehen verloren!

---

## Fehlerbehebung

### Problem: API-Authentifizierung schlägt fehl

**Symptome**: `401 Unauthorized` oder `403 Forbidden`

**Lösung**:
1. Überprüfen Sie API-Token in vault.yml:
   ```bash
   ansible-vault view vault.yml | grep proxmox
   ```
2. Testen Sie API-Zugriff manuell:
   ```bash
   curl -k "https://pve-cluster.example.com:8006/api2/json/cluster/resources" \
     -H "Authorization: PVEAPIToken=automation@pve!ansible=<token-secret>"
   ```
3. Überprüfen Sie Benutzerberechtigungen in Proxmox

### Problem: VM-ID kann nicht gefunden werden

**Symptome**: `get-vmid` Task schlägt fehl

**Lösung**:
1. Überprüfen Sie Hostname-Übereinstimmung:
   ```bash
   # Auf Ansible-Host
   ansible <host> -m setup -a "filter=ansible_hostname"
   
   # In Proxmox
   # VM-Name muss mit Hostname übereinstimmen
   ```
2. Manuelle VM-ID-Ermittlung:
   ```bash
   pvesh get /cluster/resources --type vm
   ```
3. Setzen Sie VM-ID manuell:
   ```yaml
   -e "proxmox_vmid=100"
   ```

### Problem: Snapshot-Erstellung timeout

**Symptome**: Task hängt oder timeout nach langer Zeit

**Lösung**:
1. Überprüfen Sie Proxmox-Storage-Performance
2. Überprüfen Sie Storage-Kapazität:
   ```bash
   pvesm status
   ```
3. Reduzieren Sie VM-RAM (weniger Snapshot-Größe):
   - Snapshots mit RAM benötigen mehr Zeit
   - Erwägen Sie `snapshots ohne RAM` (in Proxmox-Config)
4. Erhöhen Sie Ansible-Timeout:
   ```yaml
   async: 3600  # 1 Stunde
   poll: 10
   ```

### Problem: Alte Snapshots werden nicht gelöscht

**Symptome**: Mehr als 2 Snapshots vorhanden

**Lösung**:
1. Manuelle Bereinigung:
   ```bash
   ansible-playbook playbooks/cleanups/clean-pve-snapshots.yml \
     -i inventories/... \
     -K --ask-vault-pass
   ```
2. Überprüfen Sie Snapshot-Liste:
   ```bash
   qm listsnapshot <vmid>
   ```
3. Manuell löschen via CLI:
   ```bash
   qm delsnapshot <vmid> <snapshot-name>
   ```

### Problem: Nicht genug Speicherplatz für Snapshot

**Symptome**: `no space left on device`

**Lösung**:
1. Überprüfen Sie Storage-Nutzung:
   ```bash
   pvesm status
   df -h
   ```
2. Bereinigen Sie alte Snapshots:
   ```bash
   # Alle VMs, alle Snapshots
   for vmid in $(qm list | awk 'NR>1 {print $1}'); do
     qm delsnapshot $vmid <old-snapshot-name>
   done
   ```
3. Erweitern Sie Storage oder verschieben Sie VMs

---

## Monitoring und Reporting

### Snapshot-Übersicht abrufen

```bash
# Via Ansible ad-hoc
ansible localhost \
  -m uri \
  -a "url=https://{{ proxmox_host }}:8006/api2/json/nodes/{{ proxmox_node }}/qemu/{{ vmid }}/snapshot headers={'Authorization':'PVEAPIToken={{ proxmox_user }}!{{ proxmox_token_id }}={{ proxmox_token_secret }}'} validate_certs=no" \
  -e @vault.yml \
  --ask-vault-pass

# Direkt auf Proxmox-Host
pvesh get /nodes/<node>/qemu/<vmid>/snapshot
```

### Alle Snapshots im Cluster

```bash
# Auf Proxmox-Host
for node in $(pvesh get /nodes --output-format json | jq -r '.[].node'); do
  echo "=== Node: $node ==="
  for vmid in $(qm list | awk 'NR>1 {print $1}'); do
    echo "VM $vmid:"
    qm listsnapshot $vmid
  done
done
```

---

## Integration mit anderen Systemen

### Backup-Integration

Snapshots sind **keine Backups**! Kombinieren Sie mit echten Backups:

1. **Proxmox Backup Server (PBS)**: Native Integration
2. **Borg/Rsync**: File-Level Backups
3. **3-2-1 Regel**: 3 Kopien, 2 Medien, 1 Offsite

### Monitoring-Integration

Überwachen Sie Snapshots mit CheckMK oder Prometheus:
- Anzahl Snapshots pro VM
- Alter des letzten Snapshots
- Snapshot-Größe
- Failed Snapshot-Operationen

---

## Weiterführende Ressourcen

### Proxmox-Dokumentation
- [Proxmox VE API](https://pve.proxmox.com/wiki/Proxmox_VE_API)
- [Snapshots and Backups](https://pve.proxmox.com/wiki/Storage:_Directory#_snapshots_and_backups)
- [Qemu/KVM Virtual Machines](https://pve.proxmox.com/wiki/Qemu/KVM_Virtual_Machines)

### Ansible Collections
- [community.general.proxmox_snap](https://docs.ansible.com/ansible/latest/collections/community/general/proxmox_snap_module.html)
- [community.general Collections](https://galaxy.ansible.com/community/general)

---

**Navigation**: [← Zurück: Security & Hardening](05-Security-Hardening.md) | [Nächstes: Basis-System →](07-Basis-System.md)