Files

Ansible Servercow da81549161 add docs

2026-06-11 18:04:41 +02:00

14 KiB

Raw Blame History

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`	Snapshot vor OS-Updates	`AUTO_before_os_update_{{ date }}`
`os-major-upgrade.yml`	Snapshot vor Major-Upgrade	`AUTO_before_major_{{ date }}`
`update-mailcow.yaml`	Snapshot vor Mailcow-Update	`pre-mailcow-update-{{ version }}`
`cleanups/clean-pve-snapshots.yml`	Snapshot-Löschung	Alle außer "current"

Beispiel-Integration in Playbook

- 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:

proxmox_host: "pve-cluster.example.com"
proxmox_user: "automation@pve"
proxmox_token_id: "ansible"
proxmox_token_secret: "<aus Vault>"

Verwendung:

- include_role:
    name: proxmox-automation
    tasks_from: get-vmid

Output:

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:

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:

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

Snapshot-Retention-Logik:

Listet alle existierenden Snapshots auf
Sortiert nach Erstellungsdatum
Löscht alle außer den letzten 2
Erstellt neuen Snapshot
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:

proxmox_vmid: 100
proxmox_host: "pve-cluster.example.com"
proxmox_user: "automation@pve"
proxmox_token_id: "ansible"
proxmox_token_secret: "<aus Vault>"

Verwendung:

- include_role:
    name: proxmox-automation
    tasks_from: delete-snapshots

Workflow:

Abruft alle Snapshots der VM
Filtert "current" aus (wird nicht gelöscht)
Iteriert über verbleibende Snapshots
Löscht jeden Snapshot
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

Vault-Konfiguration

Erforderliche Variablen in vault.yml

# 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

Login to Proxmox Web Interface
Datacenter → Permissions → API Tokens
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
Kopieren Sie den Secret (nur einmal sichtbar!)
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:

# 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:

ansible-galaxy collection install community.proxmox:1.5.0

In requirements.yml:

collections:
  - name: community.proxmox
    version: "1.5.0"

Installation via requirements:

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:

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)

# 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:

# 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:

# 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:

# 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

VM auswählen in Proxmox
Snapshots Tab öffnen
Gewünschten Snapshot auswählen
Rollback klicken
Bestätigen

⚠️ Warnung: Rollback überschreibt aktuellen Zustand!

Rollback via CLI (auf Proxmox-Host)

# 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)

- 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:

Überprüfen Sie API-Token in vault.yml:

ansible-vault view vault.yml | grep proxmox

Testen Sie API-Zugriff manuell:

curl -k "https://pve-cluster.example.com:8006/api2/json/cluster/resources" \
  -H "Authorization: PVEAPIToken=automation@pve!ansible=<token-secret>"

Überprüfen Sie Benutzerberechtigungen in Proxmox

Problem: VM-ID kann nicht gefunden werden

Symptome: get-vmid Task schlägt fehl

Lösung:

Überprüfen Sie Hostname-Übereinstimmung:

# Auf Ansible-Host
ansible <host> -m setup -a "filter=ansible_hostname"

# In Proxmox
# VM-Name muss mit Hostname übereinstimmen

Manuelle VM-ID-Ermittlung:
```
pvesh get /cluster/resources --type vm
```
Setzen Sie VM-ID manuell:
```
-e "proxmox_vmid=100"
```

Problem: Snapshot-Erstellung timeout

Symptome: Task hängt oder timeout nach langer Zeit

Lösung:

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

Problem: Alte Snapshots werden nicht gelöscht

Symptome: Mehr als 2 Snapshots vorhanden

Lösung:

Manuelle Bereinigung:

ansible-playbook playbooks/cleanups/clean-pve-snapshots.yml \
  -i inventories/... \
  -K --ask-vault-pass

Überprüfen Sie Snapshot-Liste:
```
qm listsnapshot <vmid>
```
Manuell löschen via CLI:
```
qm delsnapshot <vmid> <snapshot-name>
```

Problem: Nicht genug Speicherplatz für Snapshot

Symptome: no space left on device

Lösung:

Überprüfen Sie Storage-Nutzung:
```
pvesm status
df -h
```

Bereinigen Sie alte Snapshots:

# Alle VMs, alle Snapshots
for vmid in $(qm list | awk 'NR>1 {print $1}'); do
  qm delsnapshot $vmid <old-snapshot-name>
done

Erweitern Sie Storage oder verschieben Sie VMs

Monitoring und Reporting

Snapshot-Übersicht abrufen

# 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

# 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:

Proxmox Backup Server (PBS): Native Integration
Borg/Rsync: File-Level Backups
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

Ansible Collections

Navigation: ← Zurück: Security & Hardening | Nächstes: Basis-System →

14 KiB Raw Blame History

Virtualisierung (Proxmox)

Übersicht

Verwendung in anderen Playbooks

Playbooks mit Proxmox-Integration

Beispiel-Integration in Playbook

Rollen

Rolle: proxmox-automation

1. get-vmid.yaml

2. create-snapshots.yaml

3. delete-snapshots.yaml

Vault-Konfiguration

Erforderliche Variablen in vault.yml

Proxmox API-Token erstellen

Benötigte Proxmox-Berechtigungen

Externe Abhängigkeiten

Community Proxmox Collection

Verwendete Module

Best Practices

1. Snapshots nur bei kritischen Operationen

2. Aussagekräftige Snapshot-Namen

3. Regelmäßiges Snapshot-Cleanup

4. Snapshot-Retention beachten

5. Storage-Kapazität überwachen

6. Snapshot-Limits beachten

Snapshot-Rollback

Manuelle Rollback über Proxmox Web-Interface

Rollback via CLI (auf Proxmox-Host)

Rollback via Ansible (manuell)

Fehlerbehebung

Problem: API-Authentifizierung schlägt fehl

Problem: VM-ID kann nicht gefunden werden

Problem: Snapshot-Erstellung timeout

Problem: Alte Snapshots werden nicht gelöscht

Problem: Nicht genug Speicherplatz für Snapshot

Monitoring und Reporting

Snapshot-Übersicht abrufen

Alle Snapshots im Cluster

Integration mit anderen Systemen

Backup-Integration

Monitoring-Integration

Weiterführende Ressourcen

Proxmox-Dokumentation

Ansible Collections

14 KiB

Raw Blame History