> 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/04-terraform-packer.md).

# Terraform & Packer

Infrastructure als Code (IaC) bringt dieselbe Versionskontrolle, Peer-Review und Wiederholbarkeit in die Bereitstellung von Infrastruktur, auf die sich Softwareteams verlassen. Die **VergeOS-Terraform-Provider** ermöglicht es Ihnen, VMs, Netzwerke und Benutzer in HCL-Konfigurationsdateien zu deklarieren, während das **Packer-Plugin** die Erstellung von Golden Images automatisiert. Zusammen bilden sie eine deklarative Pipeline: Packer erstellt die Images, Terraform deployt die Infrastruktur.

## Terraform-Provider

Der VergeOS-Terraform-Provider ist im Terraform Registry veröffentlicht und vollständig kompatibel mit **OpenTofu** (dem Open-Source-Fork von Terraform). Es ermöglicht Ihnen, VergeOS-Ressourcen über standardmäßige `terraform plan` / `terraform apply` Workflows zu verwalten.

### Provider-Konfiguration

```hcl
terraform {
  required_providers {
    vergeio = {
      source  = "verge-io/vergeio"
      version = "~> 0.1.0"
    }
  }
}

provider "vergeio" {
  host     = "https://vergeos.example.com"
  username = "admin"
  password = var.vergeos_password
  insecure = true  # Auf true setzen für selbstsignierte SSL-Zertifikate
}
```

| Parameter    | Erforderlich | Beschreibung                                                                         |
| ------------ | ------------ | ------------------------------------------------------------------------------------ |
| **host**     | Ja           | URL oder IP-Adresse des VergeOS-Systems oder -Mandanten                              |
| **username** | Ja           | VergeOS-Benutzername mit den entsprechenden Berechtigungen                           |
| **password** | Ja           | Passwort für den angegebenen Benutzer (als `sensitiv`)                               |
| **insecure** | Nein         | Setzen Sie `true` zu kennzeichnen, um selbstsignierte SSL-Zertifikate zu akzeptieren |

{% hint style="success" %}
**Mit OpenTofu kompatibel**

Die Provider-Konfiguration ist für OpenTofu identisch. Ersetzen Sie einfach `terraform` Befehle durch `tofu` — keine Codeänderungen erforderlich.
{% endhint %}

### Ressourcen

Der Provider unterstützt derzeit vier verwaltete Ressourcentypen zum Erstellen und Aktualisieren von VergeOS-Objekten:

| Ressource             | Zweck                                       | Wichtige Attribute                                                                                                                                                                              |
| --------------------- | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`vergeio_vm`**      | Virtuelle Maschinen erstellen und verwalten | `cpu_cores`, `ram`, `os_family`, `machine_type`, `ha_group`, `Cluster`, `guest_agent`, `uefi`, `secure_boot`, `snapshot_profile`, `powerstate`, inline `vergeio_drive` und `vergeio_nic` blocks |
| **`vergeio_network`** | Virtuelle Netzwerke konfigurieren           | `network_address` (CIDR), `dhcp_enabled`, `dhcp_start`, `dhcp_end`, `dns_server_list`, `gateway`, `powerstate`                                                                                  |
| **`vergeio_user`**    | Benutzer bereitstellen                      | Benutzerkontenverwaltung innerhalb von VergeOS                                                                                                                                                  |
| **`vergeio_member`**  | Gruppenmitgliedschaft verwalten             | Benutzer mit Gruppen für RBAC verknüpfen                                                                                                                                                        |

### Datenquellen

Acht schreibgeschützte Datenquellen ermöglichen es Ihnen, vorhandene VergeOS-Objekte für die Verwendung in Ihren Konfigurationen abzufragen:

| Datenquelle                  | Gibt zurück                                                |
| ---------------------------- | ---------------------------------------------------------- |
| **`vergeio_version`**        | Aktuelle VergeOS-Versionsinformationen                     |
| **`vergeio_clusters`**       | Verfügbare Compute-/Storage-Cluster                        |
| **`vergeio_nodes`**          | Knoten in der Umgebung                                     |
| **`vergeio_networks`**       | Vorhandene virtuelle Netzwerke                             |
| **`vergeio_vms`**            | Virtuelle Maschinen (nach Name, Snapshot-Status filterbar) |
| **`vergeio_groups`**         | Benutzergruppen für RBAC                                   |
| **`vergeio_mediasources`**   | Hochgeladene ISOs und Mediendateien                        |
| **`vergeio_cloudinitfiles`** | Verfügbare Cloud-Init-Konfigurationsdateien                |

### HCL-Beispiele

#### VM mit Laufwerk und NIC

Dieses Beispiel erstellt einen Linux-Webserver mit einem 10-GB-virtio-scsi-Laufwerk und einer NIC, die an ein internes Netzwerk angebunden ist:

```hcl
resource "vergeio_vm" "web_server" {
  name                 = "my-web-server"
  description          = "Webserver"
  enabled              = true
  os_family            = "linux"
  cpu_cores            = 2
  machine_type         = "q35"
  ram                  = 2048
  powerstate           = false
  guest_agent          = true
  cloudinit_datasource = "nocloud"
  ha_group             = "web"

  # Speicher
  vergeio_drive {
    name           = "Web Server OS Disk"
    description    = "Betriebssystem-Datenträger"
    disksize       = 10
    interface      = "virtio-scsi"
    preferred_tier = 3
    orderid        = 0
  }

  # Netzwerk
  vergeio_nic {
    name        = "Web Server Network"
    description = "NIC für den Webserver"
    interface   = "virtio"
    enabled     = true
    vnet        = vergeio_network.web_network.id
  }
}
```

#### Internes Netzwerk mit DHCP

```hcl
resource "vergeio_network" "web_network" {
  name            = "web-internal-network"
  network_address = "192.168.10.0/24"
  dns_server_list = ["8.8.8.8", "8.8.4.4"]
  dhcp_enabled    = true
  dhcp_start      = "192.168.10.100"
  dhcp_end        = "192.168.10.200"
}
```

#### Vorhandene VMs abfragen

Verwenden Sie Datenquellen, um auf bestehende Infrastruktur zu verweisen, ohne sie zu verwalten:

```hcl
data "vergeio_vms" "production" {
  filter_name = "prod-db"
  is_snapshot  = false
}

output "production_vms" {
  value = data.vergeio_vms.production.vms
}
```

#### Cloud-Init-Integration

Das `vergeio_vm` Die Ressource unterstützt cloud-init für die Automatisierung beim ersten Start. Das Provider-Schema stellt ein `cloudinit_datasource` Attribut auf der VM sowie eine `vergeio_cloudinitfiles` Datenquelle zum Referenzieren von bereits in VergeOS vorhandenen Cloud-Init-Dateien bereit:

```hcl
resource "vergeio_vm" "app_server" {
  name                 = "app-server-01"
  os_family            = "linux"
  cpu_cores            = 4
  machine_type         = "q35"
  ram                  = 8192
  guest_agent          = true
  cloudinit_datasource = "nocloud"

  vergeio_drive {
    name           = "OS Disk"
    disksize       = 20
    interface      = "virtio-scsi"
    preferred_tier = 2
  }

  vergeio_nic {
    interface = "virtio"
    vnet      = vergeio_network.web_network.id
  }
}
```

Für die genaue Syntax, die verwendet wird, um Cloud-Init-Dateien inline an die VM-Ressource anzuhängen (anstatt über die Datenquelle auf vorab hochgeladene Dateien zu verweisen), konsultieren Sie das [Repository des Providers](https://github.com/verge-io/terraform-provider-vergeio) — das feldbezogene Format kann sich zwischen Releases weiterentwickeln.

### Reifegrad & Roadmap

{% hint style="warning" %}
**Aktuelle Ressourcenabdeckung prüfen**

Der VergeOS-Terraform-Provider befindet sich in aktiver Entwicklung, und noch nicht jedes VergeOS-Objekt wird bereits als verwaltete Ressource bereitgestellt. Beispiele für Bereiche, die zu einem bestimmten Zeitpunkt möglicherweise nicht vollständig vom Provider abgedeckt sind, sind die Mandantenbereitstellung, die Verwaltung von Snapshot-Profilen und die Konfiguration externer/WAN-Netzwerke.

Prüfen Sie immer das [GitHub-Repository](https://github.com/verge-io/terraform-provider-vergeio) und den Terraform-Registry-Eintrag auf die aktuelle Ressourcenabdeckung und die Release Notes, bevor Sie eine Konfiguration darauf aufbauen.
{% endhint %}

## Packer-Plugin

Das **Packer-Plugin für VergeOS** (`github.com/verge-io/packer-plugin-vergeio`) automatisiert die Erstellung von VM-Images direkt auf der VergeOS-Plattform. Während Terraform laufende Infrastruktur verwaltet, konzentriert sich Packer auf das Erstellen der **goldenen Images** die als Grundlage für Bereitstellungen dienen.

### Warum Packer?

```mermaid
flowchart LR
    A["Base ISO"] --> B["Packer-Build"]
    B --> C["Pakete installieren<br/>Betriebssystem härten<br/>Dienste konfigurieren"]
    C --> D["Golden Image"]
    D --> E["VM-Rezept"]
    D --> F["Terraform-Bereitstellung"]
    D --> G["Manuelle Bereitstellung"]

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

Golden Images stellen sicher, dass jede bereitgestellte VM mit einer bekannten, getesteten und gehärteten Ausgangsbasis startet. Anstatt ein nacktes Betriebssystem bereitzustellen und bei jeder Bereitstellung Konfigurationsskripte auszuführen, erstellt Packer das Image einmal vorab:

* **Konsistenz** — Jede aus dem Image erstellte VM ist identisch
* **Geschwindigkeit** — Keine Verzögerung durch die Erststart-Bereitstellung; VMs sind sofort einsatzbereit
* **Compliance** — Sicherheits-Baselines und Patches werden bereits zur Build-Zeit integriert
* **Pipeline-Integration** — Lösen Sie Image-Neubuilds per CI/CD an Tagen mit Betriebssystem-Patches aus

### Plugin-Konfiguration

Das Packer-Plugin wird in einem `required_plugins` Block zusammen mit einem `source` und `build` für das Ziel-Image deklariert. Die genauen Feldnamen für den `source "vergeio"` Block (Endpunkt, Anmeldedaten, VM-Größe, Datenträgeroptionen usw.) sollten aus dem Plugin-Repository übernommen werden, da sie sich zwischen Releases weiterentwickeln können:

* [`verge-io/packer-plugin-vergeio` auf GitHub](https://github.com/verge-io/packer-plugin-vergeio)

Eine typische `required_plugins` Deklaration sieht folgendermaßen aus:

```hcl
packer {
  required_plugins {
    vergeio = {
      source  = "github.com/verge-io/vergeio"
      version = ">= 0.1.1"
    }
  }
}
```

### Funktionen

Auf hoher Ebene steuert das Plugin den vollständigen Packer-Build-Lebenszyklus gegen die VergeOS-API — es erstellt eine temporäre VM, führt Provisioner aus und erfasst das resultierende Image. Für das genaue Konfigurationsschema, unterstützte Gastertypen und das Verhalten bei Herunterfahren/Bereinigung verweisen Sie direkt auf das Plugin-Repository:

* [`verge-io/packer-plugin-vergeio` auf GitHub](https://github.com/verge-io/packer-plugin-vergeio)

### Packer → Rezept-Pipeline

Packer-Images integrieren sich nahtlos in das VergeOS **Rezept** System. Ein typischer Workflow:

1. **Packer** erstellt und härtet das Golden Image nach einem Zeitplan (z. B. monatlicher Patch-Zyklus)
2. Das Image wird als **VM-Rezept** im VergeOS Marketplace registriert
3. Benutzer stellen standardisierte VMs aus dem Rezept bereit — entweder über die UI oder via Terraform
4. Updates fließen automatisch: Erstellen Sie das Packer-Image neu, aktualisieren Sie das Rezept, und alle neuen Bereitstellungen erhalten die neueste Version

## IaC-Workflow-Muster

### Nur-Terraform-Workflow

Für Teams, die deklarative Infrastruktur ohne Image-Pipelines wollen:

```mermaid
flowchart LR
    A["HCL-Konfiguration"] --> B["terraform plan"]
    B --> C["terraform apply"]
    C --> D["VergeOS-API"]
    D --> E["VMs + Netzwerke<br/>erstellt"]

    style B fill:#7b42f5,color:#fff
    style C fill:#4a9eff,color:#fff
```

### Vollständige Pipeline (Packer + Terraform)

Für Produktionsumgebungen mit Golden-Image-Verwaltung:

```mermaid
flowchart LR
    A["Base ISO"] --> B["Packer-Build"]
    B --> C["Golden Image"]
    C --> D["Terraform-Bereitstellung"]
    D --> E["Produktions-VMs"]
    F["CI/CD-Trigger"] -.-> B

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

### Mit anderen Tools kombiniert

Terraform übernimmt die Bereitstellung; Konfigurationsmanagement-Tools übernehmen den Rest:

| Phase                | Tool                               | Zweck                                         |
| -------------------- | ---------------------------------- | --------------------------------------------- |
| **Image-Erstellung** | Packer                             | Gehärtete Golden Images erstellen             |
| **Bereitstellung**   | Terraform                          | VMs, Netzwerke, Benutzer bereitstellen        |
| **Konfiguration**    | Ansible / cloud-init               | Softwarekonfiguration nach der Bereitstellung |
| **Überwachung**      | Prometheus / VergeOS-Warnmeldungen | Bereitgestellte Infrastruktur überwachen      |

{% hint style="info" %}
**VMware Bridge**

Auf VMware verwaltet der vSphere-Provider von Terraform ESXi/vCenter/vSAN als separate Bereiche, und Packer verwendet den `vsphere-iso` Builder über vCenter. Der einzelne VergeOS `vergeio` Provider verwaltet VMs, Netzwerke, Laufwerke und Benutzer über einen einzigen API-Endpunkt, und das Packer-Plugin zielt auf dieselbe API ab.
{% endhint %}

{% hint style="info" %}
**Nutanix Bridge**

Der Nutanix-Terraform-Provider (`nutanix/nutanix`) und das Packer-Plugin zielen beide auf die v3-API von Prism Central ab. Der VergeOS-Provider spricht mit einem einzigen Endpunkt (der VergeOS-System- oder Mandanten-URL) ohne separate Management-Instanz und stellt die Cloud-Init-Konfiguration direkt auf der `vergeio_vm` Ressource über die `cloudinit_datasource` Attribut und die `vergeio_cloudinitfiles` Datenquelle.
{% endhint %}

## Best Practices

### Zustandsverwaltung

* **Verwenden Sie Remote-State-Backends** (S3, Consul, Terraform Cloud) für die Zusammenarbeit im Team
* **Committen Sie niemals** `terraform.tfstate` in die Versionskontrolle — es kann Anmeldedaten enthalten
* **Sperren Sie State-Dateien** um gleichzeitige Änderungen in Mehrbenutzerumgebungen zu verhindern

### Sicherheit

* **Verwenden Sie Variablen** für sensible Werte (`var.vergeos_password`) — hinterlegen Sie Anmeldedaten niemals hart im Code
* **Kennzeichnen Sie sensible Ausgaben** mit `sensitive = true` um eine versehentliche Offenlegung in Protokollen zu verhindern
* **Schränken Sie die Provider-Berechtigungen ein** — erstellen Sie einen dedizierten VergeOS-API-Benutzer mit minimal erforderlichem Zugriff

### Modulorganisation

* **Trennen Sie Umgebungen** in Workspaces oder Verzeichnisse (`dev/`, `staging/`, `prod/`)
* **Erstellen Sie wiederverwendbare Module** für gängige Muster (z. B. ein "web-server"-Modul mit VM + Netzwerk + Firewall-Regeln)
* **Fixieren Sie Provider-Versionen** um unerwartete Breaking Changes bei Upgrades zu vermeiden

## Weiterführende Lektüre

* [Terraform-Provider — GitHub](https://github.com/verge-io/terraform-provider-vergeio)
* [Terraform Registry — VergeIO-Provider](https://registry.terraform.io/providers/verge-io/vergeio/latest)
* [Packer-Plugin — GitHub](https://github.com/verge-io/packer-plugin-vergeio)
* [OpenTofu Registry — VergeIO-Provider](https://search.opentofu.org/provider/verge-io/vergeio/latest)
* [VergeOS-Dokumentation — Terraform-Provider](https://docs.verge.io/product-guide/tools-integrations/terraform-provider/)


---

# 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/04-terraform-packer.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.