> 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-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 ins Infrastrukturmanagement. Die **vergeio.vergeos** Die Ansible-Collection erweitert Ansible um speziell entwickelte Module und ein Inventory-Plugin für VergeOS und ermöglicht Ihnen, VM-Snapshots zu verwalten, Ressourcen mit Tags zu organisieren, VM-Images zu importieren und Infrastruktur über mehrere Standorte hinweg dynamisch zu entdecken — alles über vertraute YAML-Playbooks.

## Collection-Übersicht

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

| Detail                    | Wert                                                             |
| ------------------------- | ---------------------------------------------------------------- |
| **Namensraum**            | `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
# Von Galaxy installieren (empfohlen)
ansible-galaxy collection install vergeio.vergeos

# Erforderliches Python-SDK installieren
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 und hält Anmeldedaten so aus Ihren Playbooks und Inventory-Dateien heraus:

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

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

## Module

Die Collection bietet Module für VM-Lebenszyklus-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 programmatisch — 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 # Für 24 Stunden aufbewahren (Sekunden)
    quiesce: true # Das Gast-Dateisystem in einen ruhigen Zustand versetzen
```

### Tag-Verwaltungs-Module

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: Umgebung-Tag-Kategorie erstellen
  vergeio.vergeos.tag_category:
    name: "Umgebung"
    description: "Klassifizierung der Bereitstellungsumgebung"

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

### VM-Import-Funktionen

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 sowie RAM werden direkt aus der OVA ü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 ermitteln und ein Ansible-Inventory zu erstellen — so entfällt die Pflege statischer Host-Dateien.

{% hint style="warning" %}
**Nur-API-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 Ausführung von Playbooks konfigurieren.
{% endhint %}

### Inventory-Konfiguration

Erstellen Sie eine Inventory-Datei (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 Basis 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`               | Operationen auf Knotenebene                  |

### Host-Variablen

Jede erkannte VM stellt über 20 Host-Variablen bereit, darunter VM-ID, Name, CPU-Kerne, RAM, OS-Familie, Power-Status, 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 tag-basiertes Filtern mit dem dynamischen Inventory, um Snapshots standortübergreifend zu orchestrieren:

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

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

### Tag-Infrastruktur einrichten

Richten Sie in Ihrer VergeOS-Umgebung eine konsistente Tagging-Taxonomie ein:

```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: "Verantwortliche Geschäftseinheit" }
        - { name: "Compliance", description: "Regulatorischer Rahmen" }
        - { name: "Backup", description: "Backup-Richtlinienstufe" }

    - 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 für den 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 über Datei-Name oder ID auf die vorhandene OVA.
    - 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: Die importierte Vorlage markieren
      vergeio.vergeos.tag:
        category: "Umgebung"
        name: "Vorlage"
        resource_type: "vm"
        resource_name: "win2022-template"
```

## Integrationsmuster

### Terraform- und 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["OS 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                              |
| **Ermittlung**     | Inventory | VergeOS-API nach neu erstellten VMs abfragen                               |
| **Konfiguration**  | Ansible   | Pakete installieren, Dienste konfigurieren, Sicherheits-Baselines anwenden |
| **Validierung**    | Ansible   | Smoke-Tests ausführen, Konnektivität prüfen, Compliance verifizieren       |

### Python-SDK + Ansible

Für komplexe Workflows, die über das hinausgehen, 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 bei Merge in den Hauptzweig auslösen.

### 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 der `ansible-playbook` Aktion für durch Pull Requests ausgelöste Infrastrukturänderungen aus.

### AWX / Tower

Setzen Sie Ansible AWX für eine webbasierte UI, RBAC und die geplante Ausführung von Playbooks gegen VergeOS-Umgebungen ein.

## Bewährte Verfahren

### Anmeldedatenverwaltung

* **Anmeldedaten niemals fest codieren** in Playbooks oder Inventory-Dateien — verwenden Sie Umgebungsvariablen oder Ansible Vault
* **API-Schlüssel verwenden** für Servicekonten in der Produktion — sie unterstützen IP-Allow-Listen und Ablaufdaten
* **Anmeldedaten rotieren** regelmäßig und die Nutzung von API-Schlüsseln über die VergeOS-Oberfläche 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 zu beschränken — vermeiden Sie, die gesamte Umgebung zu laden
* **Inventories trennen** pro Umgebung (Dev, Staging, Produktion) aus Sicherheitsgründen

### Playbook-Design

* **Verwenden Sie `delegate_to: localhost`** für VergeOS-API-Aufrufe — die Module kommunizieren mit der API, nicht mit Gast-VMs per SSH
* **Tags nutzen** für das Targeting — sie bieten ein flexibles, mehrdimensionales Gruppierungssystem
* **Idempotenz umsetzen** — Playbooks so entwerfen, dass sie gefahrlos erneut ausgeführt werden können, ohne Seiteneffekte

{% 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 für die Host-Ermittlung. Eine einzige Inventory-Konfiguration kann mehrere VergeOS-Standorte gleichzeitig abfragen — ohne standortspezifisches Verbindungsmanagement.
{% 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/automate-protect-and-extend/de/integrationen-und-apis/python-sdk.md)
* [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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
