Servercow-Ansible/operating-automation
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

add docs

Browse Source
This commit is contained in:
Ansible Servercow
2026-06-11 18:04:41 +02:00
parent 590d37e4cf
commit da81549161
9 changed files with 5004 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

553
docs/06-Virtualisierung.md Normal file
View File

@@ -0,0 +1,553 @@
# 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)