> For the complete documentation index, see [llms.txt](https://docs.verge.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.verge.io/learn-the-platform/de/modul-8-entwicklung-and-devops/05-ansible.md).

# Ansible-Collection

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](https://github.com/verge-io/ansible-collection-vergeos) |

### Installation

Installieren Sie die Collection aus Ansible Galaxy:

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

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

```bash
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.

```yaml
- 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          |

```yaml
- 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.

{% hint style="warning" %}
**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.
{% endhint %}

### Inventory-Konfiguration

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

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

```mermaid
flowchart TD
    A["VergeOS API"] --> B["vergeos_vms Plugin"]
    B --> C["Nach Standort"]
    B --> D["Nach Status"]
    B --> E["Nach Tags"]
    B --> F["Nach Mandant"]
    B --> G["Nach OS-Familie"]
    B --> H["Nach Cluster"]
    B --> I["Nach Knoten"]

    C --> J["datacenter_east<br/>datacenter_west"]
    D --> K["status_running<br/>status_stopped"]
    E --> L["tag_Production<br/>tag_Development"]
    F --> M["tenant_acme<br/>tenant_globex"]

    style B fill:#4a9eff,color:#fff
    style A fill:#2ecc71,color:#fff
```

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

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

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

```yaml
---
- 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.

```mermaid
flowchart LR
    A["Terraform"] --> B["VMs<br/>und Netzwerke bereitstellen"]
    B --> C["Dynamisches Inventory"]
    C --> D["Ansible"]
    D --> E["Betriebssystem konfigurieren<br/>Software installieren<br/>Richtlinien anwenden"]

    style A fill:#7b42f5,color:#fff
    style D fill:#ee4444,color:#fff
    style C fill:#4a9eff,color:#fff
```

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

```yaml
- 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

{% hint style="info" %}
**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.
{% endhint %}

{% hint style="info" %}
**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.
{% endhint %}

## Weiterführende Lektüre

* [Ansible-Collection — GitHub](https://github.com/verge-io/ansible-collection-vergeos)
* [Ansible Galaxy — vergeio.vergeos](https://galaxy.ansible.com/vergeio/vergeos)
* [pyvergeos Python SDK — PyPI](https://pypi.org/project/pyvergeos/)
* [VergeOS-Dokumentation — Python SDK](https://docs.verge.io/product-guide/tools-integrations/python-sdk/)
* [Ansible-Dokumentation](https://docs.ansible.com/)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.verge.io/learn-the-platform/de/modul-8-entwicklung-and-devops/05-ansible.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.