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

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

Mit OpenTofu kompatibel

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

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:

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

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:

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:

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 — das feldbezogene Format kann sich zwischen Releases weiterentwickeln.

Reifegrad & Roadmap

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 und den Terraform-Registry-Eintrag auf die aktuelle Ressourcenabdeckung und die Release Notes, bevor Sie eine Konfiguration darauf aufbauen.

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?

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

Eine typische required_plugins Deklaration sieht folgendermaßen aus:

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

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:

Vollständige Pipeline (Packer + Terraform)

Für Produktionsumgebungen mit Golden-Image-Verwaltung:

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

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.

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.

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
• Terraform Registry — VergeIO-Provider
• Packer-Plugin — GitHub
• OpenTofu Registry — VergeIO-Provider
• VergeOS-Dokumentation — Terraform-Provider