Ansible-Sammlung

Automatisieren Sie die VergeOS-Infrastruktur mit der vergeio.vergeos-Ansible-Sammlung — Module für VM-Snapshots, Tagging und Importe sowie ein dynamisches Inventar-Plugin für Multi-Site-Umgebungen.

Ansible bringt agentenlose, Push-basierte Automatisierung in das Infrastrukturmanagement. Die vergeio.vergeos Die Ansible-Collection erweitert Ansible um speziell entwickelte Module und ein Inventory-Plugin für VergeOS und ermöglicht es Ihnen, VM-Snapshots zu verwalten, Ressourcen mit Tags zu organisieren, VM-Images zu importieren und Infrastruktur über mehrere Standorte hinweg dynamisch zu erkennen — alles über vertraute YAML-Playbooks.

Überblick über die Collection

Die VergeOS-Ansible-Collection wird auf Ansible Galaxy veröffentlicht und integriert sich direkt über das in die VergeOS REST-API pyvergeos Python SDK.

Details	Wert
Namespace	vergeio
Collection	vergeos
Vollständige Referenz	vergeio.vergeos
Python	>= 3.9
Ansible	>= 2.14.0
SDK-Abhängigkeit	pyvergeos >= 1.0.1
Quelle	GitHub

Installation

Installieren Sie die Collection aus Ansible Galaxy:

# Installation von Galaxy (empfohlen)
ansible-galaxy collection install vergeio.vergeos

# Installieren Sie das erforderliche Python-SDK
pip install pyvergeos

Für Entwicklungs- oder Offline-Umgebungen, aus dem Quellcode erstellen und installieren:

git clone https://github.com/verge-io/ansible-collection-vergeos.git
cd ansible-collection-vergeos
ansible-galaxy collection build
ansible-galaxy collection install vergeio-vergeos-*.tar.gz --force

Authentifizierung

Die Collection verwendet Umgebungsvariablen für die API-Authentifizierung, sodass Anmeldedaten aus Ihren Playbooks und Inventardateien herausgehalten werden:

export VERGEOS_HOST="https://vergeos.example.com"
export VERGEOS_USERNAME="admin"
export VERGEOS_PASSWORD="your-password"
export VERGEOS_INSECURE="true"   # Auf true setzen für selbstsignierte SSL-Zertifikate

Alternativ können Sie für nicht-interaktive Szenarien wie CI/CD-Pipelines eine API-Schlüssel-Authentifizierung verwenden. API-Schlüssel werden in System > Users > [select user] > API Keys innerhalb der VergeOS-UI erstellt und bieten Bearer-Token-Authentifizierung, ohne dass Benutzername-/Passwort-Anmeldedaten erforderlich sind.

Module

Die Collection bietet Module für VM-Lifecycle-Operationen, Tagging und Image-Verwaltung. Jedes Modul kommuniziert über das pyvergeos SDK mit der VergeOS-API.

VM-Snapshot-Modul

Das vergeio.vergeos.vm_snapshot Modul erstellt und verwaltet VM-Snapshots programmgesteuert — nützlich für Backup-Automatisierung, Prüfpunkte vor Änderungen und Disaster-Recovery-Workflows.

- name: Snapshot des Datenbankservers erstellen
  vergeio.vergeos.vm_snapshot:
    vm_name: "db-server-01"
    description: "Snapshot vor dem Upgrade"
    retention: 86400 # 24 Stunden aufbewahren (Sekunden)
    quiesce: true # Das Gast-Dateisystem stilllegen

Module zur Tag-Verwaltung

Tags bieten ein flexibles Klassifizierungssystem zur Organisation von VergeOS-Ressourcen. Die Collection enthält zwei Module für die Tag-Verwaltung:

Modul	Zweck
vergeio.vergeos.tag_category	Tag-Kategorien erstellen und verwalten (z. B. "Umgebung", "Abteilung")
vergeio.vergeos.tag	Einzelne Tags innerhalb von Kategorien anwenden und verwalten

- name: Tag-Kategorie für die Umgebung erstellen
  vergeio.vergeos.tag_category:
    name: "Umgebung"
    description: "Klassifizierung der Bereitstellungsumgebung"

- name: VM als Produktion taggen
  vergeio.vergeos.tag:
    category: "Umgebung"
    name: "Produktion"
    resource_type: "vm"
    resource_name: "web-server-01"

Funktionen zum VM-Import

Die Collection stellt VMs aus OVA-Vorlagen bereit, die bereits in VergeOS hochgeladen wurden — das vm_import Modul verweist auf eine vorhandene OVA per Name oder ID, und CPU und RAM werden aus der OVA selbst übernommen. Laden Sie die OVA zuerst hoch (UI oder API), und führen Sie dann das Playbook aus, um die VM zu erstellen.

Dynamisches Inventory-Plugin

Das vergeos_vms Inventory-Plugin fragt die VergeOS-API ab, um VMs dynamisch zu erkennen und ein Ansible-Inventar zu erstellen — damit entfällt die Notwendigkeit, statische Host-Dateien zu pflegen.

API-only Inventory

Das Inventory-Plugin ruft VM-Metadaten aus der VergeOS-API ab. Es nicht setzt ansible_host und unterstützt standardmäßig keine direkten SSH-Verbindungen. Sie müssen ansible_host über Host-Variablen, Compose-Regeln oder eine separate Verbindungsstrategie für die SSH-basierte Playbook-Ausführung konfigurieren.

Inventory-Konfiguration

Erstellen Sie eine Inventardatei (z. B. vergeos_inventory.yml):

plugin: vergeio.vergeos.vergeos_vms
sites:
  - name: "datacenter-east"
    host: "https://east.vergeos.example.com"
    username: "ansible-svc"
    password: "{{ lookup('env', 'VERGEOS_PASSWORD') }}"
    verify_ssl: false

  - name: "datacenter-west"
    host: "https://west.vergeos.example.com"
    username: "ansible-svc"
    password: "{{ lookup('env', 'VERGEOS_PASSWORD') }}"
    verify_ssl: false

# Optionale Filter
filters:
  status: "running"
  name_pattern: "prod-*"

# Caching für große Umgebungen aktivieren
cache: true
cache_plugin: jsonfile
cache_connection: /tmp/vergeos_inventory_cache
cache_timeout: 300

Automatische Gruppierung

Das Plugin organisiert erkannte VMs automatisch in Gruppen auf Grundlage mehrerer Dimensionen:

Gruppendimension	Beispielgruppen	Anwendungsfall
Standort	datacenter_east, datacenter_west	Playbooks auf bestimmte Standorte ausrichten
Status	status_running, status_stopped	Aufgaben nur auf aktiven VMs ausführen
Tags	tag_Production, tag_Development	Umgebungsspezifische Konfiguration
Mandant	tenant_acme, tenant_globex	Mandantenfähige Automatisierung
OS-Familie	os_linux, os_windows	OS-spezifische Playbooks
Cluster	cluster_compute01, cluster_compute02	Cluster-bewusste Wartung
Knoten	node_node1, node_node2	Knotenebene-Operationen

Host-Variablen

Jede erkannte VM stellt über 20 Host-Variablen bereit, darunter VM-ID, Name, CPU-Kerne, RAM, OS-Familie, Stromzustand, Cluster-Zuordnung, Knotenplatzierung, Netzwerkkonfiguration, Tags und das vollständige VM-Datenwörterbuch für fortgeschrittene Anwendungsfälle.

Playbook-Muster

Snapshot-Orchestrierung über mehrere Standorte

Verwenden Sie tagbasiertes Filtern mit dem dynamischen Inventory, um Snapshots über Standorte hinweg zu orchestrieren:

---
- name: Alle Produktionsdatenbanken über Standorte hinweg snapshotten
  hosts: tag_Production:&os_linux
  gather_facts: false

  tasks:
    - name: Vor-Wartungs-Snapshot erstellen
      vergeio.vergeos.vm_snapshot:
        vm_name: "{{ inventory_hostname }}"
        description: "Geplanter Wartungs-Snapshot - {{ ansible_date_time.date }}"
        retention: 172800 # 48 Stunden Aufbewahrungszeit
        quiesce: true
      delegate_to: localhost

Einrichtung der Tag-Infrastruktur

Etablieren Sie eine konsistente Tagging-Taxonomie in Ihrer VergeOS-Umgebung:

---
- name: Tag-Infrastruktur konfigurieren
  hosts: localhost
  connection: local

  tasks:
    - name: Tag-Kategorien erstellen
      vergeio.vergeos.tag_category:
        name: "{{ item.name }}"
        description: "{{ item.description }}"
      loop:
        - { name: "Umgebung", description: "Bereitstellungsumgebung" }
        - { name: "Abteilung", description: "Verantwortlicher der Geschäftseinheit" }
        - { name: "Compliance", description: "Regulatorischer Rahmen" }
        - { name: "Backup", description: "Stufe der Backup-Richtlinie" }

    - name: Umgebungstags auf VMs anwenden
      vergeio.vergeos.tag:
        category: "Umgebung"
        name: "Produktion"
        resource_type: "vm"
        resource_name: "{{ item }}"
      loop:
        - "db-server-01"
        - "web-server-01"
        - "app-server-01"

Workflow zum Import von Windows-VMs

Automatisieren Sie den Import von Windows-VM-Vorlagen aus OVA-Dateien:

---
- name: Windows-Server-Vorlage importieren
  hosts: localhost
  connection: local

  tasks:
    # Laden Sie win2022-standard.ova zuerst in VergeOS hoch (UI oder API);
    # vm_import verweist auf die vorhandene OVA über Dateiname oder ID.
    - name: Windows Server 2022 aus OVA importieren
      vergeio.vergeos.vm_import:
        name: "win2022-template"
        ova_file_name: "win2022-standard.ova"
        preferred_tier: "4"
        override_drive_interface: virtio
        override_nic_interface: virtio

    - name: Importierte Vorlage taggen
      vergeio.vergeos.tag:
        category: "Umgebung"
        name: "Vorlage"
        resource_type: "vm"
        resource_name: "win2022-template"

Integrationsmuster

Terraform- + Ansible-Pipeline

Ein gängiges Muster kombiniert Terraform für die Bereitstellung mit Ansible für die Konfiguration: Terraform beschreibt die Infrastruktur, Ansible konfiguriert, was darin ausgeführt wird.

Phase	Tool	Verantwortung
Bereitstellung	Terraform	VMs, Netzwerke, Benutzer, Laufwerke erstellen
Erkennung	Inventory	VergeOS-API nach neu erstellten VMs abfragen
Konfiguration	Ansible	Pakete installieren, Dienste konfigurieren, Sicherheits-Baselines anwenden
Validierung	Ansible	Smoketests ausführen, Konnektivität verifizieren, Compliance prüfen

Python SDK + Ansible

Für komplexe Workflows, die programmgesteuerte Logik über das hinaus benötigen, was YAML-Playbooks bieten, kombinieren Sie das pyvergeos Python SDK mit Ansible:

- name: Benutzerdefinierte VergeOS-Automatisierung mit Python
  hosts: localhost
  tasks:
    - name: Erweiterte VM-Operationen über pyvergeos ausführen
      ansible.builtin.script:
        cmd: scripts/bulk_snapshot.py
      environment:
        VERGEOS_HOST: "{{ vergeos_host }}"
        VERGEOS_USERNAME: "{{ vergeos_user }}"
        VERGEOS_PASSWORD: "{{ vergeos_password }}"

CI/CD-Integration

Ansible-Playbooks lassen sich natürlich in CI/CD-Pipelines für die Infrastrukturautomatisierung integrieren:

GitLab CI

Ansible-Playbooks aus .gitlab-ci.yml Stufen für automatisierte VM-Bereitstellung und Konfiguration beim Merge in main.

Jenkins

Verwenden Sie das Ansible-Plugin für Jenkins, um Playbooks als Build-Schritte auszuführen, wobei Anmeldedaten über den Jenkins Credential Store verwaltet werden.

GitHub Actions

Führen Sie Ansible-Playbooks in GitHub-Actions-Workflows mit dem ansible-playbook Action für durch Pull Requests ausgelöste Infrastrukturänderungen aus.

AWX / Tower

Stellen Sie Ansible AWX mit einer webbasierten UI, RBAC und geplanter Playbook-Ausführung gegen VergeOS-Umgebungen bereit.

Best Practices

Anmeldedatenverwaltung

• Anmeldedaten niemals hart kodieren in Playbooks oder Inventardateien — verwenden Sie Umgebungsvariablen oder Ansible Vault
• Verwenden Sie API-Schlüssel für Dienstkonten in der Produktion — sie unterstützen IP-Allow-Listen und Ablaufdaten
• Anmeldedaten regelmäßig rotieren und die Nutzung von API-Schlüsseln über die VergeOS-UI prüfen

Inventory-Strategie

• Caching aktivieren für große Umgebungen, um API-Aufrufe zu reduzieren und Playbook-Läufe zu beschleunigen
• Filter verwenden um das Inventory auf relevante VMs einzugrenzen — vermeiden Sie es, die gesamte Umgebung zu laden
• Getrennte Inventories pro Umgebung (dev, staging, production) aus Sicherheitsgründen

Playbook-Design

• Verwenden Sie delegate_to: localhost für VergeOS-API-Aufrufe — die Module sprechen mit der API, nicht per SSH mit Gast-VMs
• Tags nutzen für das Targeting — sie bieten ein flexibles, multidimensionales Gruppierungssystem
• Idempotenz implementieren — entwerfen Sie Playbooks, die ohne Nebenwirkungen sicher erneut ausgeführt werden können

Kommen Sie von VMware?

Das vergeio.vergeos Die Collection folgt dem Standard-Ansible-Muster, das Sie bereits kennen: API-gesteuerte Module für Ressourcenoperationen plus ein dynamisches Inventory-Plugin zur Host-Erkennung. Eine einzige Inventory-Konfiguration kann mehrere VergeOS-Standorte gleichzeitig abfragen — kein standortweises Verbindungs-Hopping nötig.

Kommen Sie von Nutanix?

Das vergeio.vergeos Die Collection folgt dem Standard-Ansible-Muster: API-gesteuerte Module plus ein dynamisches Inventory-Plugin. Eine Inventory-Konfiguration kann mehrere VergeOS-Standorte gleichzeitig ansprechen, ohne dass eine zentrale Management-Ebene erforderlich ist.

Weiterführende Lektüre

• Ansible-Collection — GitHub
• Ansible Galaxy — vergeio.vergeos
• pyvergeos Python SDK — PyPI
• VergeOS-Dokumentation — Python SDK
• Ansible-Dokumentation