Aufbau und Betrieb abstimmen: WZ-IT plant, implementiert und betreibt Kubernetes auf Proxmox. Die Auslegung verbindet Hypervisor, Kubernetes, Netzwerk und Storage.
Diese Anleitung erstellt einen neuen k3s-Cluster in Proxmox-KVM-VMs: drei Server mit Embedded etcd, optional zusätzliche Worker und ein fester API-Endpunkt. Sie konkretisiert den Aufbau, während die Architekturübersicht die Betriebsmodelle vergleicht. Für die Plattformwahl gibt es Proxmox vs Kubernetes.
Stand: Oktober 2026. Befehle und Adressen sind ein anzupassendes Gerüst für neue VMs. Installieren Sie k3s nicht auf dem Proxmox-Host. Bestehende Cluster werden nicht neu initialisiert.
Inhaltsverzeichnis
- 1. Topologie und Voraussetzungen
- 2. Cloud-Init-Template und VMs
- 3. Netzwerk und API-Endpunkt
- 4. k3s initialisieren und Server verbinden
- 5. Worker und Clusterzugang
- 6. Storage, Backup und Abnahme
- Quellen
1. Topologie und Voraussetzungen
Für Embedded-etcd-HA benötigt k3s mindestens drei Server; Worker heißen bei k3s Agents und sind optional. Server können auch Workloads ausführen. Prüfen Sie vorab Ressourcen und Datenträger anhand der k3s-Anforderungen. Hersteller-Mindestwerte sind keine Dimensionierung für Ihre Anwendungen. Verwenden Sie ausreichend schnellen Speicher für etcd und planen Sie Reserve für Wartung und Ausfälle.
| Rolle | Beispieladresse | Platzierung für Hostausfallschutz |
|---|---|---|
| API-Endpunkt | 10.20.0.10, api.k8s.example.test | Redundanter TCP-Load-Balancer vor den Servern |
| cp1 | 10.20.0.11 | Proxmox-Host A |
| cp2 | 10.20.0.12 | Proxmox-Host B |
| cp3 | 10.20.0.13 | Proxmox-Host C |
| Worker nach Bedarf | Aus dem eigenen Node-Netz | Nach Kapazität und Anwendung verteilen |
Alle Adressen und Namen sind Beispiele. Drei VMs auf einem Host sind ein Laboraufbau mit gemeinsamem Ausfallpunkt. Eine redundante API-IP ersetzt keine unabhängigen Hosts, Strom-, Netzwerk- oder Storage-Pfade. RKE2 ist ein anderer Installationsweg; die Distributionsauswahl und die Talos-Anleitung behandeln Alternativen.
2. Cloud-Init-Template und VMs
Folgen Sie dem dokumentierten Proxmox-Cloud-Init-Ablauf: ein Cloud-Image des ausgewählten Linux-Herstellers beziehen und dessen Prüfsumme verifizieren, eine neue VM anlegen, die Image-Disk importieren und als Bootdisk verbinden. Ergänzen Sie ein Cloud-Init-Laufwerk sowie die zum Image passenden Controller- und Konsoleneinstellungen. Prüfen Sie Image, Gastbetriebssystem und k3s-Version gemeinsam gegen die Anforderungen.
Vor dem ersten Boot jedes Klons setzen Sie in Proxmox Cloud-Init einen administrativen Benutzer, dessen SSH-Schlüssel, eine eigene IP samt Gateway und die DNS-Konfiguration. Wandeln Sie die ausgeschaltete Basis in ein Template um und erstellen Sie daraus drei vollständige Klone. Jeder Gast erhält eine eigene VM-ID, MAC-Adresse und einen eindeutigen Hostnamen. Das Template enthält noch keinen k3s-Zustand und keine Cluster-Secrets.
Starten Sie die Klone auf den vorgesehenen Hosts. Kontrollieren Sie im Gast die fertige Cloud-Init-Verarbeitung mit cloud-init status --wait, IP, DNS-Auflösung, Zeitsynchronisation und SSH-Zugang. Notieren Sie VM-ID und Hostzuordnung. Das offizielle Quelldokument zur Cloud-Init-Unterstützung beschreibt Template, Klonen und IP-/Schlüsselzuweisung ebenfalls.
3. Netzwerk und API-Endpunkt
Node-, Pod- und Service-Netze dürfen sich nicht mit vorhandenen Netzen überschneiden. Der folgende Aufbau verwendet die k3s-Defaults für Pod- und Service-CIDR nur, wenn diese in Ihrer Umgebung frei sind. Andernfalls setzen Sie cluster-cidr und service-cidr auf allen Servern identisch, bevor der Cluster entsteht. Prüfen Sie Netzanforderungen und Firewall-Regeln, ohne pauschal die Firewall abzuschalten.
| Verkehr | Freigabe im beschriebenen Modell |
|---|---|
| Nodes und administrativer Zugang zur API | TCP 6443 zu API-Endpunkt und Servern |
| Embedded etcd | TCP 2379 und 2380 zwischen Servern |
| Flannel VXLAN | UDP 8472 zwischen Nodes, nicht öffentlich |
| Kubelet und Metrics | TCP 10250 zwischen Nodes |
Vor dem Bootstrap richten Sie den TCP-Load-Balancer mit Health-Checks auf die drei Serveradressen an Port 6443 ein. Ein einzelner Load Balancer wäre erneut ein Ausfallpunkt; für das HA-Ziel gehören redundante Instanzen und deren IP-Umschaltung zur Voraussetzung. DNS zeigt auf die API-IP. Prüfen Sie Routing und die IP-Zuständigkeit, bevor diese Adresse verwendet wird.
Diese API-IP ist kein Kubernetes-Anwendungs-LoadBalancer. Ein Kubernetes Service vom Typ LoadBalancer, Ingress und Zertifikate für Anwendungen werden getrennt geplant. Mitgelieferte Komponenten wie Traefik und ServiceLB bleiben in diesem Beispiel zunächst auf ihrem k3s-Standard; alternative Controller erst nach einer bewussten Entscheidung einführen.
4. k3s initialisieren und Server verbinden
Arbeiten Sie innerhalb der neuen Linux-VMs mit administrativen Rechten. Legen Sie /etc/rancher/k3s/ mit Zugriff nur für root an. Erstellen Sie auf cp1 die Datei /etc/rancher/k3s/config.yaml und schützen Sie sie mit Dateimodus 0600. Ersetzen Sie den Token-Platzhalter durch ein langes zufälliges Secret aus Ihrer geschützten Secret-Verwaltung.
# Nur cp1 bei der erstmaligen Initialisierung
cluster-init: true
token: "REPLACE_WITH_PRIVATE_CLUSTER_SECRET"
tls-san:
- "10.20.0.10"
- "api.k8s.example.test"
write-kubeconfig-mode: "0600"
Der Konfigurationspfad und die YAML-Optionen sind dokumentiert. Wählen Sie eine konkrete freigegebene k3s-Version aus den Release Notes und setzen Sie K3S_VERSION auf deren vollständigen Release-Tag. Verwenden Sie denselben Wert auf allen neuen Nodes. Anschließend auf cp1:
# K3S_VERSION zuvor auf einen konkreten freigegebenen Tag setzen
: "${K3S_VERSION:?Konkreten k3s-Release-Tag setzen}"
curl -fL https://get.k3s.io -o install-k3s.sh
# Skript vor der Ausführung prüfen
sudo env INSTALL_K3S_VERSION="${K3S_VERSION:?Konkreten k3s-Release-Tag setzen}" sh install-k3s.sh server
sudo k3s kubectl get nodes -o wide
Auf cp2 und cp3 erstellen Sie jeweils eine eigene geschützte config.yaml. Verwenden Sie den gemeinsamen Token, dieselben TLS-Namen und gegebenenfalls identische angepasste CIDRs. Kein cluster-init auf diesen Nodes:
server: "https://10.20.0.10:6443"
token: "REPLACE_WITH_PRIVATE_CLUSTER_SECRET"
tls-san:
- "10.20.0.10"
- "api.k8s.example.test"
write-kubeconfig-mode: "0600"
Sobald cp1 über den Load Balancer erreichbar ist, führen Sie denselben versionsgebundenen Installationsblock mit Rolle server nacheinander auf cp2 und cp3 aus. Prüfen Sie nach jedem Beitritt den Node-Zustand. Das ist der dokumentierte HA-Bootstrap mit gemeinsamem Token, hier mit festem API-Zugang. Wiederholen Sie die Initialisierung nicht als Reparatur eines bereits vorhandenen Clusters.
5. Worker und Clusterzugang
Für jede zusätzliche Worker-VM erstellen Sie vor der Installation eine root-geschützte config.yaml mit server: "https://10.20.0.10:6443" und demselben privaten Token. Laden und prüfen Sie das Installationsskript wie oben, setzen Sie denselben Release-Tag und verwenden Sie die Rolle agent:
: "${K3S_VERSION:?Konkreten k3s-Release-Tag setzen}"
sudo env INSTALL_K3S_VERSION="${K3S_VERSION:?Konkreten k3s-Release-Tag setzen}" sh install-k3s.sh agent
Auf einem Server kontrollieren Sie Nodes und System-Pods:
sudo k3s kubectl get nodes -o wide
sudo k3s kubectl get pods -A -o wide
sudo k3s kubectl get --raw='/readyz?verbose'
Die administrative Kubeconfig liegt laut k3s-Clusterzugang unter /etc/rancher/k3s/k3s.yaml. Legen Sie auf dem vorgesehenen Admin-Rechner das Verzeichnis ~/.kube mit Dateimodus 0700 an beziehungsweise prüfen Sie dessen Schutz. Übertragen Sie die Datei geschützt als ~/.kube/proxmox-k3s.yaml mit Dateimodus 0600, ohne eine vorhandene Konfiguration zu überschreiben. Ersetzen Sie in dieser Kopie den Wert von server durch https://api.k8s.example.test:6443 beziehungsweise Ihren tatsächlichen API-Endpunkt. Sie enthält administrative Zugangsdaten; nicht in Git ablegen und nicht allgemein lesbar machen. Prüfen Sie anschließend auf dem Admin-Rechner den Zugriff über den Load Balancer ausdrücklich mit dieser Datei:
kubectl --kubeconfig ~/.kube/proxmox-k3s.yaml get nodes
6. Storage, Backup und Abnahme
Der mitgelieferte Local Path Provisioner stellt node-lokalen Speicher bereit, keine automatische Replikation. Ein vorhandenes Proxmox-Ceph wird nicht allein durch die Installation zur Kubernetes-StorageClass. Wählen Sie ein passendes CSI-/Storage-Modell, bevor persistente Anwendungen starten. Prüfen Sie eine Test-PVC, Schreib-/Lesezugriff und das Verhalten bei geplantem Node-Wechsel anhand der Volume-Eigenschaften.
Für Embedded etcd können Sie auf einem Server einen manuellen Snapshot anfordern:
sudo k3s etcd-snapshot save --name acceptance
sudo k3s etcd-snapshot ls
Der Snapshot-Befehl bestätigt noch keine Wiederherstellbarkeit. Sichern Sie Snapshot und den tatsächlichen Server-Token aus /var/lib/rancher/k3s/server/token getrennt vom Cluster und zugriffsgeschützt; der Restore benötigt den Token. Anwendungsdaten werden zusätzlich gesichert. Planen Sie den isolierten Wiederherstellungstest nach Kubernetes Backup und Restore.
| Abnahme | Nachweis vor Produktivbetrieb |
|---|---|
| Control Plane | Drei Server-Nodes bereit, API-Zustand und Hostzuordnung dokumentiert |
| Netzwerk | Node-Kommunikation, DNS und Pod-Verkehr geprüft |
| Anwendung | Eigene Testanwendung über den vorgesehenen Zugangsweg erreichbar |
| Persistenz | Gewählte StorageClass und Datenzugriff nach zulässigem Wiederanlauf geprüft |
| Ausfall | Genehmigter Test eines einzelnen Hosts und des API-Load-Balancers; Quorum und Anwendung beobachten |
| Wiederherstellung | etcd samt Token und Anwendungsdaten isoliert wiederhergestellt |
Führen Sie Ausfalltests nur nach vereinbartem Plan in der Testumgebung aus. Ein gesunder Node-Status allein ist keine vollständige Abnahme. Dieses Gerüst ergänzt weder automatische Härtung noch einen fertigen Produktionsbetrieb.
Von der Installation zum Betrieb: Kubernetes auf Proxmox verbindet den vereinbarten Cluster-Aufbau mit Netzwerk-, Storage- und Betriebsplanung. Die Architekturübersicht ordnet HA und Lebenszyklen beider Ebenen ein.
