> 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. Das **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 baut die Images, Terraform stellt die Infrastruktur bereit. ## Terraform-Provider Der VergeOS Terraform-Provider wird im 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 zu verwalten. ### 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 # 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` auf true, 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 fünf 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` Blöcke | | **`vergeio_network`** | Virtuelle Netzwerke konfigurieren | `Netzwerk` (CIDR), `dhcp_enabled`, `dhcp_start`, `dhcp_stop`, `vnet_default_gateway`, `powerstate` | | **`vergeio_user`** | Benutzer bereitstellen | Benutzerkontoverwaltung innerhalb von 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-Betriebssystemdatenträger" description = "Datenträger des Betriebssystems" disksize = 10 interface = "virtio-scsi" preferred_tier = 3 orderid = 0 } # Vernetzung vergeio_nic { name = "Webserver-Netzwerk" description = "NIC für 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 = "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 Provider-Schema stellt ein `cloudinit_datasource` Attribut auf der VM und eine `vergeio_cloudinitfiles` Datenquelle zum Verweisen auf cloud-init-Dateien bereit, die bereits in VergeOS 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-Datenträger" disksize = 20 interface = "virtio-scsi" preferred_tier = 2 } vergeio_nic { interface = "virtio" vnet = vergeio_network.web_network.id } } ``` Für die genaue Syntax zum Inline-Anfügen von cloud-init-Dateien an die VM-Ressource (statt bereits hochgeladene Dateien über die Datenquelle zu referenzieren) konsultieren Sie das [Provider-Repository](https://github.com/verge-io/terraform-provider-vergeio) — die feldspezifische Form kann sich zwischen Releases weiterentwickeln. ### Reifegrad & Roadmap {% hint style="warning" %} **Aktuelle Ressourcendeckung prüfen** Der VergeOS Terraform-Provider befindet sich in aktiver Entwicklung, und noch nicht jedes VergeOS-Objekt ist als verwaltete Ressource verfügbar. Beispiele für Bereiche, die zu einem bestimmten Zeitpunkt möglicherweise keine vollständige Provider-Abdeckung haben, sind Mandantenbereitstellung, Verwaltung von Snapshot-Profilen und Konfiguration externer/WAN-Netzwerke. Prüfen Sie immer das [GitHub-Repository](https://github.com/verge-io/terraform-provider-vergeio) und den Eintrag im Terraform Registry auf die aktuelle Ressourcendeckung 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["Base ISO"] --> B["Packer Build"] B --> C["Pakete installieren
OS härten
Dienste konfigurieren"] C --> D["Golden Image"] D --> E["VM-Rezept"] D --> F["Terraform-Deployment"] 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 OS bereitzustellen und bei jedem Deployment Konfigurationsskripte auszuführen, baut Packer das Image einmal vor: * **Konsistenz** — Jede aus dem Image erstellte VM ist identisch * **Geschwindigkeit** — Keine Verzögerung durch Initialbereitstellung beim ersten Start; VMs sind sofort einsatzbereit * **Compliance** — Sicherheits-Baselines und Patches werden zur Build-Zeit eingebettet * **Pipeline-Integration** — Image-Neuerstellungen aus CI/CD an OS-Patchtagen auslösen ### Plugin-Konfiguration Das Packer-Plugin wird in einem `required_plugins` -Block zusammen mit einem `source` und `build` für das Zielimage deklariert. Die genauen Feldnamen für den `source "vergeio"` Block (Endpunkt, Anmeldedaten, VM-Sizing, Datenträgeroptionen usw.) sollten dem Plugin-Repository entnommen 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 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 Herunterfahr-/Bereinigungsverhalten lesen Sie direkt im Plugin-Repository nach: * [`verge-io/packer-plugin-vergeio` auf GitHub](https://github.com/verge-io/packer-plugin-vergeio) ### Packer → Recipes-Pipeline Packer-Images integrieren sich nahtlos in das VergeOS- **Rezept-** System. Ein typischer Workflow: 1. **Packer** baut und härtert das Golden Image nach einem Zeitplan auf (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. Aktualisierungen fließen automatisch: Packer-Image neu erstellen, Rezept aktualisieren, 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
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-Deployment"] 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-Alarme | Bereitgestellte Infrastruktur beobachten | {% hint style="info" %} **VMware-Brücke** 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-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 mit einem einzigen Endpunkt (der URL des VergeOS-Systems oder -Mandanten), ohne separate Management-Instanz, und stellt cloud-init-Konfiguration direkt auf der `vergeio_vm` Ressource über das `cloudinit_datasource` Attribut und die `vergeio_cloudinitfiles` Datenquelle bereit. {% endhint %} ## Best Practices ### State-Verwaltung * **Verwenden Sie entfernte State-Backends** (S3, Consul, Terraform Cloud) für die Zusammenarbeit im Team * **Committen Sie niemals** `terraform.tfstate` in die Versionsverwaltung — 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`) — Anmeldedaten niemals hart kodieren * **Markieren Sie sensible Ausgaben** mit `sensitive = true` um unbeabsichtigte Offenlegung in Logs zu verhindern * **Provider-Berechtigungen einschränken** — erstellen Sie einen dedizierten VergeOS-API-Benutzer mit den minimal erforderlichen Rechten ### Modulorganisation * **Umgebungen trennen** in Workspaces oder Verzeichnisse (`dev/`, `staging/`, `prod/`) * **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/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 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=&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.