> 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

Deklarative Infrastructure-as-Code für VergeOS mit dem Terraform-Provider, OpenTofu und dem Packer-Plugin für die automatisierte Erstellung von Golden Images.

Infrastructure-as-Code (IaC) bringt dieselbe Versionskontrolle, Peer-Review und Wiederholbarkeit in die Infrastrukturbereitstellung, auf die Softwareteams setzen. Der **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. Gemeinsam bilden sie eine deklarative Pipeline: Packer erstellt die Images, Terraform stellt die Infrastruktur bereit.

## Terraform-Provider

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

### Provider-Konfiguration

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

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

| 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 `sensitive`)              |
| **markieren** | Nein         | Auf `true` setzen, um selbstsignierte SSL-Zertifikate zu akzeptieren |

{% hint style="success" %}
**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 fünf verwaltete Ressourcentypen zum Erstellen und Aktualisieren von VergeOS-Objekten:

| Ressource                | Zweck                                       | Schlüsselattribute                                                                                                                                                                                   |
| ------------------------ | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`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`, eingebettet `vergeio_drive` und `vergeio_nic` Blöcke |
| **`vergeio_network`**    | Virtuelle Netzwerke konfigurieren           | `Netzwerk` (CIDR), `dhcp_enabled`, `dhcp_start`, `dhcp_stop`, `vnet_default_gateway`, `powerstate`                                                                                                   |
| **`vergeio_user`**       | Benutzer bereitstellen                      | Benutzerkontenverwaltung in VergeOS                                                                                                                                                                  |
| **`vergeio_member`**     | Gruppenmitgliedschaft verwalten             | Benutzer Gruppen für RBAC zuordnen                                                                                                                                                                   |
| **`vergeio_tag_member`** | Tags Objekten zuweisen                      | Tags an VMs, Netzwerke und andere VergeOS-Objekte anhängen (VergeOS v26+)                                                                                                                            |

### Datenquellen

Zehn 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                |
| **`vergeio_resource_groups`** | Hardware-Ressourcengruppen (PCI-, USB-, vGPU-Pools)        |
| **`vergeio_tags`**            | In VergeOS konfigurierte Tags                              |

### 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 angeschlossen 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           = "Webserver-OS-Disk"
    description    = "Betriebssystemdisk"
    disksize       = 10
    interface      = "virtio-scsi"
    preferred_tier = 3
    orderid        = 0
  }

  # Netzwerk
  vergeio_nic {
    name        = "Webserver-Netzwerk"
    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-internes-netzwerk"
  network      = "192.168.10.0/24"
  dhcp_enabled = true
  dhcp_start   = "192.168.10.100"
  dhcp_stop    = "192.168.10.200"
}
```

#### Vorhandene VMs abfragen

Verwenden Sie Datenquellen, um auf vorhandene 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

Die `vergeio_vm` Ressource unterstützt Cloud-Init für die Automatisierung beim ersten Start. Das Schema des Providers stellt ein `cloudinit_datasource` Attribut auf der VM und eine `vergeio_cloudinitfiles` Datenquelle zum Verweisen auf Cloud-Init-Dateien bereit, die in VergeOS bereits vorhanden sind:

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

Die genaue Syntax zum inline-Anhängen von Cloud-Init-Dateien an die VM-Ressource (anstatt vorab hochgeladene Dateien über die Datenquelle zu referenzieren) finden Sie im [Provider-Repository](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 nicht jedes VergeOS-Objekt ist bereits als verwaltete Ressource verfügbar. Beispiele für Bereiche, die zu einem bestimmten Zeitpunkt möglicherweise noch nicht vollständig vom Provider abgedeckt sind, umfassen Tenant-Bereitstellung, Snapshot-Profilverwaltung und externe/WAN-Netzwerkkonfiguration.

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

## Packer-Plugin

Die **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 die laufende Infrastruktur verwaltet, konzentriert sich Packer auf das Erstellen der **Golden Images** die als Grundlage für Bereitstellungen dienen.

### Warum Packer?

```mermaid
flowchart LR
    A["Basis-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 von einer bekannten, getesteten und gehärteten Ausgangsbasis startet. Anstatt ein nacktes Betriebssystem bereitzustellen und bei jeder Bereitstellung Konfigurationsskripte auszuführen, bereitet Packer das Image einmal vor:

* **Konsistenz** — Jede VM, die aus dem Image erstellt wird, ist identisch
* **Geschwindigkeit** — Keine Verzögerung durch Bereitstellung beim ersten Start; VMs sind sofort einsatzbereit
* **Compliance** — Sicherheits-Baselines und Patches werden bereits zur Build-Zeit eingebaut
* **Pipeline-Integration** — Image-Neuerstellungen bei OS-Patch-Tagen aus CI/CD auslösen

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

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

### Funktionen

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

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

### Packer → Rezepte-Pipeline

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

1. **Packer** erstellt und härtert das Golden Image nach 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 per Terraform
4. Aktualisierungen fließen automatisch: Packer-Image neu erstellen, Rezept aktualisieren, und alle neuen Bereitstellungen erhalten die neueste Version

## IaC-Workflow-Muster

### Terraform-Only-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
```

### Gesamte Pipeline (Packer + Terraform)

Für Produktionsumgebungen mit Golden-Image-Verwaltung:

```mermaid
flowchart LR
    A["Basis-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 beobachten      |

{% hint style="info" %}
**VMware-Brücke**

In VMware verwaltet der vSphere-Provider von Terraform ESXi/vCenter/vSAN als separate Belange, 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-Brücke**

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

## Best Practices

### State-Management

* **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 Umgebungen mit mehreren Benutzern zu verhindern

### Sicherheit

* **Verwenden Sie Variablen** für sensible Werte (`var.vergeos_password`) — Anmeldedaten niemals fest eincodieren
* **Markieren 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 den minimal erforderlichen Rechten

### Modulorganisation

* **Trennen Sie Umgebungen** in Workspaces oder Verzeichnisse (`Entwicklung/`, `Staging/`, `Produktion/`)
* **Wiederverwendbare Module erstellen** für gängige Muster (z. B. ein „web-server“-Modul mit VM + Netzwerk + Firewall-Regeln)
* **Provider-Versionen festlegen** 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/automate-protect-and-extend/de/integrationen-und-apis/terraform-provider.md)


---

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