Wer Proxmox VE im Unternehmen betreibt, kennt das Problem: VMs und Container werden manuell über die Weboberfläche angelegt, Konfigurationen sind nicht dokumentiert und bei einem Neuaufbau beginnt alles von vorn. Infrastructure as Code (IaC) löst dieses Problem — und mit dem Terraform-Provider für Proxmox wird die gesamte Virtualisierungsumgebung in versionierbarem, reproduzierbarem Code abgebildet.

Was ist Infrastructure as Code?

Infrastructure as Code bedeutet, dass Infrastruktur nicht manuell konfiguriert, sondern in deklarativen Dateien beschrieben wird. Die Vorteile sind erheblich:

Reproduzierbarkeit: Jede Umgebung lässt sich identisch neu aufbauen
Versionierung: Änderungen an der Infrastruktur werden per Git nachverfolgt
Review-Prozesse: Infrastruktur-Änderungen durchlaufen Code-Reviews
Dokumentation: Der Code selbst dokumentiert den Soll-Zustand

Terraform von HashiCorp hat sich als Standard für IaC etabliert. Es arbeitet provider-basiert: Für jede Plattform — ob Cloud oder On-Premises — gibt es einen Provider, der die API-Kommunikation übernimmt.

Der bpg/proxmox Terraform Provider

Der Community-Provider bpg/proxmox ist der ausgereifteste Terraform-Provider für Proxmox VE. Er unterstützt VMs, LXC-Container, Storage, Netzwerke und Benutzer-Management über die Proxmox-API.

API-Token in Proxmox erstellen

Terraform kommuniziert über API-Tokens mit Proxmox. Erstellen Sie einen dedizierten Benutzer mit den nötigen Rechten:

# Benutzer und Token anlegen
pveum user add terraform@pve
pveum aclmod / -user terraform@pve -role PVEAdmin
pveum user token add terraform@pve terraform-token --privsep 0

Den ausgegebenen Token-Wert sicher speichern — er wird nur einmal angezeigt.

Provider-Konfiguration

Die Provider-Konfiguration in Terraform verweist auf die Proxmox-API:

terraform {
  required_providers {
    proxmox = {
      source  = "bpg/proxmox"
      version = ">= 0.78.0"
    }
  }
}

provider "proxmox" {
  endpoint  = "https://proxmox.example.com:8006/"
  api_token = var.proxmox_api_token
  insecure  = false

  ssh {
    agent = true
  }
}

Das API-Token wird als Variable übergeben und nie im Code gespeichert. Der ssh-Block ermöglicht Terraform, Dateien direkt auf den Proxmox-Host zu übertragen — etwa Cloud-Init-Konfigurationen.

VMs mit Cloud-Init erstellen

Das Herzstück: Eine VM als Terraform-Ressource definieren. Mit Cloud-Init wird die VM beim ersten Boot automatisch konfiguriert:

resource "proxmox_virtual_environment_vm" "webserver" {
  name      = "web-prod-01"
  node_name = "pve01"
  tags      = ["production", "web"]

  clone {
    vm_id = 9000  # Cloud-Init Template
  }

  cpu {
    cores = 4
    type  = "x86-64-v2-AES"
  }

  memory {
    dedicated = 8192
  }

  disk {
    datastore_id = "local-zfs"
    interface    = "scsi0"
    size         = 50
  }

  network_device {
    bridge  = "vmbr0"
    vlan_id = 100
  }

  initialization {
    ip_config {
      ipv4 {
        address = "10.0.100.10/24"
        gateway = "10.0.100.1"
      }
    }
    user_account {
      keys     = [file("~/.ssh/id_ed25519.pub")]
      username = "deploy"
    }
  }
}

Ein terraform apply erstellt diese VM in wenigen Sekunden — vollständig konfiguriert, mit SSH-Zugang und der richtigen Netzwerkanbindung.

LXC-Container erstellen

Für leichtgewichtige Workloads eignen sich LXC-Container. Auch sie lassen sich per Terraform verwalten:

resource "proxmox_virtual_environment_container" "dns" {
  description = "Internal DNS resolver"
  node_name   = "pve01"
  tags        = ["infrastructure", "dns"]

  operating_system {
    template_file_id = "local:vztmpl/debian-12-standard_12.7-1_amd64.tar.zst"
    type             = "debian"
  }

  cpu {
    cores = 2
  }

  memory {
    dedicated = 1024
  }

  disk {
    datastore_id = "local-zfs"
    size         = 10
  }

  network_interface {
    name    = "eth0"
    bridge  = "vmbr0"
    vlan_id = 10
  }
}

Variablen und Module für Wiederverwendbarkeit

Hardcodierte Werte machen Code unflexibel. Terraform-Variablen und -Module lösen das:

# variables.tf
variable "vm_configs" {
  type = map(object({
    cores  = number
    memory = number
    disk   = number
    vlan   = number
    ip     = string
  }))
}

# terraform.tfvars
vm_configs = {
  "web-prod-01" = { cores = 4, memory = 8192, disk = 50, vlan = 100, ip = "10.0.100.10/24" }
  "app-prod-01" = { cores = 8, memory = 16384, disk = 100, vlan = 200, ip = "10.0.200.10/24" }
  "db-prod-01"  = { cores = 8, memory = 32768, disk = 500, vlan = 300, ip = "10.0.300.10/24" }
}

Mit for_each iteriert Terraform über die Map und erstellt alle VMs aus einer einzigen Ressourcen-Definition. Für unternehmensweite Standards empfiehlt sich ein eigenes Terraform-Modul, das VM-Erstellung, Netzwerkanbindung und Tagging in einem wiederverwendbaren Paket kapselt.

Plan, Apply, Destroy — der Terraform-Workflow

Terraform arbeitet in drei Phasen:

terraform plan — Zeigt an, welche Ressourcen erstellt, geändert oder gelöscht werden
terraform apply — Führt die geplanten Änderungen aus
terraform destroy — Entfernt alle verwalteten Ressourcen

Der plan-Schritt ist entscheidend: Er zeigt den Diff zwischen Soll- und Ist-Zustand, bevor Änderungen wirksam werden. In CI/CD-Pipelines wird der Plan automatisch generiert und erst nach Freigabe angewendet.

State-Management mit Remote Backend

Terraform speichert den Zustand aller verwalteten Ressourcen in einer State-Datei. Für Teams ist ein lokales State-File problematisch — ein Remote Backend schafft Abhilfe:

terraform {
  backend "s3" {
    bucket   = "terraform-state"
    key      = "proxmox/production.tfstate"
    endpoint = "https://minio.example.com"
    region   = "us-east-1"
  }
}

Ein S3-kompatibles Backend (z. B. MinIO auf dem eigenen TrueNAS) bietet State-Locking, Versionierung und gleichzeitigen Zugriff für mehrere Teammitglieder.

Manuell vs. Ansible vs. Terraform

Aspekt	Manuell (GUI)	Ansible	Terraform
VM-Erstellung	Klick-basiert	Möglich (API-Module)	Native Stärke
Konfiguration	Manuell	Native Stärke	Begrenzt (Cloud-Init)
Zustandsverwaltung	Keine	Keine (imperative Runs)	State-Datei (deklarativ)
Drift-Erkennung	Keine	Keine	Automatisch via `plan`
Lernkurve	Niedrig	Mittel	Mittel
Skalierung	Schlecht	Gut	Sehr gut

Terraform + Ansible: Die ideale Kombination

In der Praxis ergänzen sich Terraform und Ansible optimal. Terraform erstellt die Infrastruktur — VMs, Container, Netzwerke — und Ansible konfiguriert anschließend das Betriebssystem, installiert Software und härtet die Systeme. Ein typischer Workflow:

Terraform erstellt die VM mit Cloud-Init (Netzwerk, SSH-Key)
Terraform gibt die IP-Adresse als Output aus
Ansible übernimmt: Pakete installieren, Dienste konfigurieren, Hardening

Dieser Ansatz trennt Infrastruktur-Provisionierung sauber von Konfigurationsmanagement und nutzt die Stärken beider Werkzeuge.

Monitoring mit DATAZONE Control

Automatisiert erstellte Infrastruktur braucht automatisiertes Monitoring. DATAZONE Control erkennt neue VMs und Container automatisch, überwacht Ressourcen-Auslastung, Backup-Status und Netzwerkverfügbarkeit. In Kombination mit Terraform entsteht ein vollständig automatisierter Kreislauf: Infrastruktur per Code erstellen, automatisch überwachen und bei Problemen sofort alarmieren.

Sie möchten Ihre Proxmox-Umgebung mit Terraform automatisieren? Kontaktieren Sie uns — wir implementieren Infrastructure as Code für Ihre Proxmox-Infrastruktur und begleiten Sie von der Planung bis zum produktiven Betrieb.

Proxmox Terraform Provider: Infrastructure as Code für Proxmox VE