WZ-IT plant und implementiert Kubernetes auf Proxmox, einschließlich automatisiertem Cluster-Aufbau. Die Auslegung umfasst Hosts, Netzwerk, Storage und den anschließenden Betrieb.
Diese Anleitung ergänzt die manuelle Talos-Installation um OpenTofu und die Provider bpg/proxmox und siderolabs/talos. Sie verwendet ISO-Boot und die Talos-API. Ein NoCloud-Import oder ein Gastzugang per SSH ist dafür nicht nötig.
Stand: Oktober 2026. Die Beispiele folgen den unten verlinkten Provider- und Herstellerdokumentationen. Sie sind ein an die eigene Umgebung anzupassendes Aufbaugerüst.
Inhaltsverzeichnis
- 1. Voraussetzungen und State
- 2. Provider und Eingaben
- 3. Proxmox-VMs deklarieren
- 4. Talos-Konfiguration anwenden
- 5. Bootstrap und Zugang
- 6. Plan, Ausführung und Abnahme
- Grenzen und Betrieb
- Quellen
1. Voraussetzungen und State
Proxmox ist installiert. Der ausführende Rechner erreicht die Proxmox-API und die Node-IPs auf der Talos-API. API-Token und Berechtigungen werden nach der bpg-Provider-Dokumentation eingerichtet. PROXMOX_VE_ENDPOINT und PROXMOX_VE_API_TOKEN kommen aus der geschützten Laufzeitumgebung; das API-Zertifikat muss dort vertrauenswürdig sein.
Ein Talos-ISO aus der Image Factory liegt auf allen beteiligten Hosts unter derselben Storage-Datei-ID. Talos-Version, Schematic und Installer-Image gehören zusammen. Die manuelle Anleitung erläutert Image-Auswahl und Disk-Prüfung. Das Beispiel startet mit deaktiviertem Proxmox Guest Agent, damit dessen Bereitschaft im Maintenance-Modus nicht vorausgesetzt wird.
Der Kubernetes-Endpunkt ist hier ein vorab eingerichteter TCP-Load-Balancer auf Port 6443 zu den Control-Plane-IPs, mit passendem DNS-Namen. Er wird nicht durch den Code angelegt. Node-IPs entstehen durch DHCP-Reservierungen für die im Code festgelegten MAC-Adressen. Für HA: drei Control Planes auf getrennten Hosts; Worker nach Bedarf. Eine einzelne Control Plane ist nur das kleinere Laborziel.
State, Plan-Dateien und exportierte Zugänge enthalten vertrauliche Daten. Nach der OpenTofu-State-Dokumentation schützt sensitive nur die Anzeige. Ein zugriffsbeschränktes Backend mit Sperren und Sicherung sowie verschlüsselte Ablage einrichten, bevor Secrets entstehen. State und Zugänge gehören nicht ins Git-Repository.
2. Provider und Eingaben
In main.tf die Provider explizit festlegen. Diese Pins referenzieren die geprüften Dokumentationsstände, keine allgemeine Zusage über zukünftige Kompatibilität. Bei Änderungen Lockfile und Schema gemeinsam prüfen.
terraform {
required_providers {
proxmox = {
source = "bpg/proxmox"
version = "0.117.0"
}
talos = {
source = "siderolabs/talos"
version = "0.12.0"
}
}
}
provider "proxmox" {}
provider "talos" {}
In variables.tf die Eingaben deklarieren:
variable "nodes" {
type = map(object({
host = string
id = number
ip = string
mac = string
role = string
}))
}
variable "iso_file_id" { type = string }
variable "datastore" { type = string }
variable "cluster_endpoint" { type = string }
variable "talos_version" { type = string }
variable "kubernetes_version" { type = string }
variable "installer_image" { type = string }
variable "bootstrap_node" { type = string }
In einer lokalen terraform.tfvars alle Werte setzen: nodes enthält pro Node Proxmox-Host, freie VM-ID, reservierte IP, eindeutige MAC und Rolle controlplane oder worker. bootstrap_node ist der Schlüssel einer Control Plane aus dieser Map. iso_file_id ist die vorhandene ISO-Datei-ID, datastore das Ziel für EFI- und Systemdisk. cluster_endpoint ist die vollständige HTTPS-URL des Load-Balancers mit Port 6443. Talos- und Kubernetes-Version sowie das vollständige Image-Factory-Installer-Image bewusst auswählen; keine latest-Tags verwenden.
3. Proxmox-VMs deklarieren
In main.tf ergänzen. Hostnamen, Bridge und Ressourcengrößen auf das eigene Inventar abstimmen. Die Systemdisk ist hier leer; niemals bestehende Datenplatten zuweisen. UEFI, VirtIO SCSI und abgeschaltetes Ballooning folgen der Talos-Proxmox-Anleitung.
resource "proxmox_virtual_environment_vm" "node" {
for_each = var.nodes
name = each.key
node_name = each.value.host
vm_id = each.value.id
bios = "ovmf"
machine = "q35"
scsi_hardware = "virtio-scsi-pci"
boot_order = ["scsi0", "ide2"]
started = true
agent { enabled = false }
cpu {
cores = each.value.role == "controlplane" ? 2 : 4
type = "host"
}
memory {
dedicated = each.value.role == "controlplane" ? 4096 : 8192
floating = 0
}
efi_disk {
datastore_id = var.datastore
type = "4m"
pre_enrolled_keys = false
}
disk {
datastore_id = var.datastore
interface = "scsi0"
size = 100
}
cdrom {
enabled = true
file_id = var.iso_file_id
interface = "ide2"
}
network_device {
bridge = "vmbr0"
model = "virtio"
mac_address = each.value.mac
}
lifecycle { prevent_destroy = true }
}
prevent_destroy blockiert geplante Zerstörung und Ersetzung bei vorhandenem Ressourcenblock; es ist kein Backup und schützt nicht vor manuellem Löschen oder dem Entfernen des Blocks. Der Code verwaltet ausschließlich neu anzulegende VMs, keine automatische Übernahme vorhandener VMs. Siehe OpenTofu lifecycle.
4. Talos-Konfiguration anwenden
Ein gemeinsames Secrets-Bundle bildet die Identität des Clusters. Nicht bei jedem Lauf neu erzeugen. Die Maschinenkonfiguration wird je Rolle abgeleitet; apply verwendet die reservierte Node-IP. /dev/sda vor der ersten Anwendung im Maintenance-Modus prüfen und nötigenfalls anpassen. depends_on ordnet die Ressourcen, ersetzt aber keine Erreichbarkeitsprüfung der Talos-API nach dem Boot.
resource "talos_machine_secrets" "cluster" {
talos_version = var.talos_version
lifecycle { prevent_destroy = true }
}
data "talos_machine_configuration" "node" {
for_each = var.nodes
cluster_name = "talos-proxmox"
cluster_endpoint = var.cluster_endpoint
machine_type = each.value.role
machine_secrets = talos_machine_secrets.cluster.machine_secrets
talos_version = var.talos_version
kubernetes_version = var.kubernetes_version
config_patches = [yamlencode({
machine = {
install = {
disk = "/dev/sda"
image = var.installer_image
}
}
})]
}
resource "talos_machine_configuration_apply" "node" {
for_each = var.nodes
node = each.value.ip
client_configuration = talos_machine_secrets.cluster.client_configuration
machine_configuration_input = data.talos_machine_configuration.node[each.key].machine_configuration
depends_on = [proxmox_virtual_environment_vm.node]
}
5. Bootstrap und Zugang
Der Bootstrap läuft einmal auf der gewählten Control Plane, nachdem die Konfigurationen angewendet sind. kubeconfig und talosconfig werden als vertrauliche Outputs bereitgestellt. Talos-Endpunkte sind direkte Control-Plane-IPs, nicht der Kubernetes-Load-Balancer.
resource "talos_machine_bootstrap" "cluster" {
node = var.nodes[var.bootstrap_node].ip
client_configuration = talos_machine_secrets.cluster.client_configuration
depends_on = [talos_machine_configuration_apply.node]
}
resource "talos_cluster_kubeconfig" "cluster" {
node = var.nodes[var.bootstrap_node].ip
client_configuration = talos_machine_secrets.cluster.client_configuration
depends_on = [talos_machine_bootstrap.cluster]
}
data "talos_client_configuration" "cluster" {
cluster_name = "talos-proxmox"
client_configuration = talos_machine_secrets.cluster.client_configuration
endpoints = [for node in values(var.nodes) : node.ip if node.role == "controlplane"]
nodes = [for node in values(var.nodes) : node.ip]
}
output "talosconfig" {
value = data.talos_client_configuration.cluster.talos_config
sensitive = true
}
output "kubeconfig" {
value = talos_cluster_kubeconfig.cluster.kubeconfig_raw
sensitive = true
}
6. Plan, Ausführung und Abnahme
Erst nach Einrichtung von Backend, Eingaben, Zertifikatsvertrauen und Zugängen ausführen. Den Plan auf VM-IDs, Hostzuordnung, Disk-Ziele und unerwartete Ersetzungen prüfen. Bei API-Erreichbarkeitsfehlern den Node-Zustand prüfen, statt Secrets oder State zu löschen. Nach einer Unterbrechung erneut planen.
Für health den Platzhalter <CONTROL_PLANE_IP> durch die IP genau einer Control Plane ersetzen, beispielsweise die von bootstrap_node. Die erzeugte talosconfig enthält alle Nodes; Talos 1.14 verlangt für diesen Aufruf genau einen Zielnode, über den die Clusterprüfung läuft (Stand 19.10.2026).
tofu init
tofu fmt -check
tofu validate
tofu plan -out=cluster.plan
tofu apply cluster.plan
umask 077
tofu output -raw talosconfig > talosconfig
tofu output -raw kubeconfig > kubeconfig
talosctl --talosconfig ./talosconfig --nodes "<CONTROL_PLANE_IP>" health
kubectl --kubeconfig ./kubeconfig get nodes -o wide
Die Abnahme umfasst außerdem die Erreichbarkeit des Kubernetes-Endpunkts, DNS, CNI, einen Testworkload sowie Storage und Restore, sofern eingerichtet. Ohne funktionsfähiges CNI sind Nodes möglicherweise noch nicht Ready. Die Ressourcen allein richten keine StorageClass, Ingress-Regeln oder Anwendungsbackups ein.
Grenzen und Betrieb
Provider-State ersetzt weder etcd- noch Anwendungsbackups. Den Wiederherstellungsweg separat anhand von Kubernetes-Backup und Restore prüfen. Ein Versionswechsel in HCL ist kein vollständiges Upgrade-Runbook; Talos- und Kubernetes-Upgrades getrennt planen. Bei verlorenem State bestehende Secrets und Ressourcen sichern und die dokumentierten Importmöglichkeiten prüfen; einen laufenden Cluster nicht neu bootstrappen.
WZ-IT verbindet den automatisierten Aufbau auf Proxmox mit der Architekturplanung. Für laufende Pflege ist Managed Kubernetes der passende Anschluss. Die manuelle Anleitung bleibt der Bezug für Image, Node-Diagnose und Upgradepfad.
