Kubernetes-Cluster auf Proxmox erstellen: Schritt-für-Schritt-Anleitung

Die Erstellung eines Kubernetes-Clusters auf Proxmox ermöglicht es Ihnen, in einer virtualisierten und selbst gehosteten Umgebung eine performante Container-Orchestrierungsplattform zu betreiben. Diese ist ideal für Testumgebungen, Entwicklungs- und CI-Workflows oder auch kleinere Produktionsszenarien. In dieser Anleitung erfahren Sie Schritt für Schritt, wie Sie auf Proxmox virtuelle Maschinen einrichten und daraus ein stabiles Kubernetes-Cluster aufbauen.

Schritt 1: Voraussetzungen prüfen

Bevor Sie mit der eigentlichen Einrichtung des Kubernetes-Clusters beginnen, sollten Sie sicherstellen, dass Ihre Umgebung alle technischen Voraussetzungen erfüllt. Eine saubere Ausgangsbasis erspart später viel Zeit und vermeidet Konfigurationsfehler.

Sie benötigen zunächst eine funktionierende Proxmox VE-Installation. Aus Leistungsgründen empfiehlt sich eine Bare-Metal-Installation von Proxmox. Sowohl der Web-Zugang über die Proxmox-Oberfläche als auch der SSH-Zugang zur Kommandozeile sollten verfügbar sein. Über SSH können Sie Befehle ausführen, Images hochladen und Konfigurationen automatisieren.

Für ein stabiles Kubernetes-Cluster benötigen Sie außerdem mehrere virtuelle Maschinen. Empfohlen werden folgende Kubernetes-Nodes:

• ein Master-Node (für die sogenannte Control Plane) und
• mindestens zwei Worker-Nodes.

Damit erreichen Sie eine gewisse Redundanz und können Kubernetes so betreiben, wie es in echten Produktionsumgebungen vorgesehen ist. Für Testzwecke genügt jedoch auch ein kleineres Setup mit einem Master und einem Worker.

Ihr Proxmox-Host sollte außerdem über eine funktionierende Bridge-Schnittstelle verfügen, die den virtuellen Maschinen den Zugang ins lokale Netzwerk und ggf. ins Internet ermöglicht. Das ist wichtig, damit die VMs später Updates herunterladen und Kubernetes-Komponenten installieren können.

Schritt 2: Cloud-Image herunterladen und als Template vorbereiten

Kubernetes-Installationen lassen sich am einfachsten mit sogenannten Cloud-Images durchführen. Diese vorkonfigurierten Betriebssystem-Images, meist Ubuntu oder Debian, sind für den automatischen Start mit cloud-init optimiert. Wir verwenden in diesem Beispiel ein Ubuntu 22.04 LTS Cloud-Image, da es stabil, gut dokumentiert und optimal für den Einsatz mit Kubernetes geeignet ist.

Zunächst laden Sie das aktuelle Ubuntu Cloud-Image direkt auf Ihren Proxmox-Host herunter. Melden Sie sich dazu per SSH auf Ihrem Proxmox-Server an und wechseln Sie in das Verzeichnis, in dem Proxmox ISO- und Image-Dateien speichert:

cd /var/lib/vz/template/iso

Laden Sie anschließend das Ubuntu-Image mit folgendem Befehl herunter:

wget -O ubuntu-22.04-server-cloudimg-amd64.img https://cloud-images.ubuntu.com/releases/22.04/release/ubuntu-22.04-server-cloudimg-amd64.img

scp ubuntu-22.04-server-cloudimg-amd64.img root@<proxmox-ip>:/var/lib/vz/template/iso/

Sobald das Image auf dem Proxmox-Host liegt, können Sie daraus eine neue virtuelle Maschine erstellen, die später als Template dient. Erstellen Sie für diesen Zweck zunächst eine leere VM mit einer eindeutigen ID, zum Beispiel 9000, und weisen Sie ihr grundlegende Hardware-Ressourcen zu:

qm create 9000 --name ubuntu-template --memory 2048 --net0 virtio,bridge=vmbr0

Nun importieren Sie das zuvor heruntergeladene Cloud-Image als virtuelle Festplatte in den gewünschten Speicher (in unserem Beispiel local-lvm):

qm importdisk 9000 /var/lib/vz/template/iso/ubuntu-22.04-server-cloudimg-amd64.img local-lvm

Anschließend können Sie die importierte Festplatte mit der VM verbinden und den richtigen Controller einstellen. Auf diese Weise wird das Image an den virtuellen SCSI-Controller der virtuellen Maschine gebunden:

qm set 9000 --scsihw virtio-scsi-pci --scsi0 local-lvm:vm-9000-disk-0

Damit Sie später beim Klonen der VMs automatisch IP-Adressen, Hostnamen und SSH-Schlüssel setzen können, benötigen Sie ein Cloud-Init-Laufwerk. Dieses virtuelle Laufwerk enthält die beim Starten der VM automatisch angewendeten Konfigurationsdaten. Fügen Sie das Cloud-Init-Drive hinzu und definieren Sie die Bootreihenfolge mit folgenden Befehlen:

qm set 9000 --ide2 local-lvm:cloudinit
qm set 9000 --boot c --bootdisk scsi0

Aktivieren Sie zusätzlich den QEMU Guest Agent, damit Proxmox später Statusinformationen aus der VM auslesen kann, und konfigurieren Sie eine serielle Konsole, um im Notfall direkten Zugriff auf die VM-Konsole zu haben:

qm set 9000 --agent 1
qm set 9000 --serial0 socket --vga serial0

Wenn alles korrekt eingerichtet ist, können Sie Ihre virtuelle Maschine in ein sogenanntes Template umwandeln. Templates dienen in Proxmox als Vorlage, aus der Sie später beliebig viele Klone erstellen können. Sie eignen sich somit perfekt für Ihre Kubernetes-Nodes.

qm template 9000

Nach diesem Schritt steht Ihnen das Ubuntu-Template bereit, das als Grundlage für Ihre Kubernetes-Master- und Worker-Knoten dient.

Schritt 3: VMs für Master/Worker per CLI klonen

In einem dritten Schritt erstellen Sie aus dem zuvor angelegten Template die virtuellen Maschinen, die später als Master- und Worker-Knoten Ihres Kubernetes-Clusters dienen. Jede dieser VMs erhält eine eigene IP-Adresse, einen eindeutigen Hostnamen sowie einen SSH-Schlüssel für den sicheren Zugriff. Proxmox übernimmt die Grundkonfiguration automatisch über cloud-init, sodass Sie keine manuelle Einrichtung mehr innerhalb der virtuellen Maschinen durchführen müssen.

Klonen Sie zunächst das zuvor erstellte Template (in diesem Beispiel mit der ID 9000) und legen Sie daraus drei virtuelle Maschinen an: eine für den Master-Knoten und zwei für die entsprechenden Worker-Knoten. Dabei können Sie CPU und Arbeitsspeicher individuell anpassen:

qm clone 9000 101 --name k8s-master-1 --full true
qm set 101 --cores 2 --memory 4096
qm clone 9000 102 --name k8s-worker-1 --full true
qm set 102 --cores 2 --memory 4096
qm clone 9000 103 --name k8s-worker-2 --full true
qm set 103 --cores 2 --memory 4096

Anschließend definieren Sie über cloud-init die grundlegenden Netzwerkeinstellungen, den Hostnamen und den SSH-Key. Dabei können Sie feste IP-Adressen vergeben oder DHCP nutzen. In diesem Beispiel werden statische Adressen verwendet:

# Master konfigurieren
qm set 101 --ipconfig0 ip=192.168.1.10/24,gw=192.168.1.1
qm set 101 --sshkey "$(cat ~/.ssh/id_rsa.pub)qm set 101 --ciuser ubuntu
qm set 101 --nameserver 192.168.1.1
qm set 101 --description "K8s Master 1"
# Worker konfigurieren
qm set 102 --ipconfig0 ip=192.168.1.11/24,gw=192.168.1.1
qm set 102 --sshkey "$(cat ~/.ssh/id_rsa.pub)qm set 102 --ciuser ubuntu
qm set 103 --ipconfig0 ip=192.168.1.12/24,gw=192.168.1.1
qm set 103 --sshkey "$(cat ~/.ssh/id_rsa.pub)qm set 103 --ciuser ubuntu

Zum Schluss starten Sie alle drei Maschinen mit den untenstehenden Terminalbefehlen:

qm start 101
qm start 102
qm start 103

Warten Sie einen Moment, bis die Systeme vollständig hochgefahren sind, und testen Sie dann die Verbindung per SSH. Wenn alles funktioniert, können Sie sich beispielsweise mit folgendem Befehl auf dem Master-Knoten anmelden:

ssh ubuntu@192.168.1.10

Schritt 4: Basis-Konfiguration auf allen virtuellen Maschinen hinzufügen

Bevor Sie Kubernetes auf den VMs installieren, sollten Sie einige systemweite Einstellungen vornehmen, die für den stabilen Betrieb erforderlich sind. Dazu gehören das Deaktivieren von Swap, das Anpassen von Kernel-Parametern für Netzwerk und IP-Forwarding sowie die Synchronisation der Systemzeit. Diese Maßnahmen sorgen dafür, dass Kubernetes korrekt arbeiten kann und Netzwerkfunktionen innerhalb der Container zuverlässig funktionieren.

Zunächst deaktivieren Sie Swap auf allen Nodes, da Kubernetes dies für die Scheduler-Logik verlangt. Außerdem entfernen Sie den entsprechenden Eintrag in /etc/fstab, damit Swap nach einem Neustart nicht erneut aktiviert wird:

sudo swapoff -a
sudo sed -i '/ swap / s/^/#/' /etc/fstab

Anschließend konfigurieren Sie die Kernel-Parameter, um sicherzustellen, dass Netzwerkpakete zwischen Containern und Knoten korrekt verarbeitet werden können:

cat <<'EOF' | sudo tee /etc/sysctl.d/k8s.conf
net.bridge.bridge-nf-call-iptables = 1
net.ipv4.ip_forward = 1
net.bridge.bridge-nf-call-ip6tables = 1
EOF
# Änderungen anwenden
sudo sysctl --system

Ein weiterer wichtiger Schritt ist die Synchronisation der Systemzeit, damit Zertifikate und Cluster-Komponenten keine Probleme aufgrund abweichender Zeiten verursachen. Dazu können Sie chrony installieren und starten:

sudo apt update && sudo apt install -y chrony
sudo systemctl enable --now chrony

Schließlich empfiehlt es sich, einige grundlegende Hilfsprogramme zu installieren, die für spätere Schritte nützlich sind:

sudo apt install -y curl apt-transport-https ca-certificates gnupg lsb-release

Nach diesen Schritten sind alle Nodes einheitlich vorbereitet, Swap ist deaktiviert, die Netzwerkeinstellungen sind korrekt gesetzt und die Zeit synchronisiert. Ihre VMs sind nun bereit für die Installation von Kubernetes und den Aufbau Ihres Clusters.

Schritt 5: Wahl der Kubernetes-Distribution

Bevor Sie mit der eigentlichen Installation von Kubernetes beginnen, sollten Sie sich für eine passende Distribution entscheiden. Auf Basis Ihrer Anforderungen können Sie zwischen zwei empfehlenswerten Varianten wählen:

• RKE2 (Rancher Kubernetes Engine 2): RKE2 ist eine stabile, production-ready Kubernetes-Distribution, die von Rancher entwickelt wird. Sie eignet sich besonders, wenn Sie später eine grafische Verwaltung über Rancher nutzen möchten oder ein Cluster mit mehreren Control-Plane-Nodes planen.
• k3s: k3s ist eine schlanke Kubernetes-Distribution, die ideal für Testumgebungen, Home-Labs oder ressourcenbegrenzte Systeme ist. Sie ist sehr einfach zu installieren und benötigt weniger Speicher und CPU.

Für den Aufbau eines robusten Kubernetes-Clusters auf Proxmox, das auch in einem produktionsnahen Szenario betrieben werden könnte, empfiehlt sich RKE2. Wenn Sie jedoch schnell ein kleines Test- oder Entwicklungscluster einrichten möchten, ist k3s die praktischere Alternative. Im weiteren Verlauf dieser Anleitung wird RKE2 genutzt.

Schritt 6: RKE2 auf dem Master installieren

Nachdem die Basis-Konfiguration Ihrer virtuellen Maschinen abgeschlossen ist, können Sie mit der Installation von RKE2 auf dem Master-Knoten beginnen. Melden Sie sich dazu per SSH auf dem Master-Node an:

ssh ubuntu@192.168.1.10

Laden Sie nun das RKE2-Installationsskript herunter und führen Sie es aus. Dabei können Sie optional einen Kanal mit der gewünschten Version angeben:

curl -sfL https://get.rke2.io | sudo INSTALL_RKE2_CHANNEL=v1.28 bash -

Nach der Installation aktivieren Sie den RKE2-Serverdienst und starten ihn sofort:

sudo systemctl enable --now rke2-server.service

Überprüfen Sie mit folgendem Befehl, ob der RKE2-Server korrekt läuft:

sudo systemctl status rke2-server

Um das Kubernetes-Cluster von Ihrem lokalen Rechner aus verwalten zu können, kopieren Sie die kubeconfig-Datei:

sudo chmod 644 /etc/rancher/rke2/rke2.yaml
scp ubuntu@192.168.1.10:/etc/rancher/rke2/rke2.yaml ~/rke2-kubeconfig

Anschließend passen Sie die Master-IP in der Datei an, damit kubectl korrekt auf den Server zugreift:

sed -i 's/127.0.0.1:6443/192.168.1.10:6443/' ~/rke2-kubeconfig
export KUBECONFIG=~/rke2-kubeconfig

Mit diesem Befehl können Sie nun prüfen, ob der Master-Node erreichbar ist:

kubectl get nodes

Wenn der Master angezeigt wird, ist die Installation erfolgreich abgeschlossen und Sie können im nächsten Schritt die Worker-Knoten hinzufügen.

Schritt 7: RKE2-Agent auf den Worker-Knoten installieren

Nachdem der Master-Knoten erfolgreich eingerichtet wurde, können Sie nun die Worker-Knoten in Ihr Cluster integrieren. Dazu installieren Sie auf jedem Worker den RKE2-Agent und verbinden ihn mit dem Master.

Auf dem Master-Knoten benötigen Sie zunächst das Node-Token, das für die Authentifizierung der Worker beim Cluster erforderlich ist:

sudo cat /var/lib/rancher/rke2/server/node-token

Notieren Sie sich das Token. Sie benötigen den Wert gleich auf den Worker-Knoten.

Melden Sie sich per SSH auf jedem Worker-Knoten an:

ssh ubuntu@192.168.1.11

Laden Sie das Installationsskript für RKE2 herunter und installieren Sie den Agenten mit folgendem Befehl:

curl -sfL https://get.rke2.io | sudo INSTALL_RKE2_CHANNEL=v1.28 sh -

Erstellen Sie anschließend die Konfigurationsdatei für den Agenten und tragen dort die Master-IP sowie den Node-Token ein:

sudo mkdir -p /etc/rancher/rke2
cat <<EOF | sudo tee /etc/rancher/rke2/config.yaml
server: https://192.168.1.10:9345
token: <TOKEN_HIER_EINFÜGEN>
EOF

Abschließend aktivieren und starten Sie den RKE2-Agent-Dienst:

sudo systemctl enable --now rke2-agent.service

Wiederholen Sie diesen Vorgang für alle Worker-Knoten im Cluster. Nach einigen Minuten können Sie auf dem Master überprüfen, ob die Worker-Knoten korrekt verbunden sind:

kubectl get nodes

Sie sollten nun alle Nodes sehen, den Master sowie die neu hinzugefügten Worker. Damit ist Ihr Cluster vollständig und bereit für die Installation von Netzwerk-Plugins, Load Balancer und weiteren Kubernetes-Komponenten.

Schritt 8: Netzwerk-CNI und LoadBalancer installieren

Nachdem Master- und Worker-Knoten erfolgreich eingerichtet sind, benötigen Sie ein Container Network Interface (CNI), damit die Pods im Cluster miteinander kommunizieren können, sowie einen Load Balancer, um Services im Netzwerk erreichbar zu machen. In dieser Anleitung verwenden wir Calico als CNI und MetalLB für die Layer-2-Load-Balancing-Funktionalität.

Calico stellt die Netzwerkverbindungen zwischen den Pods her, regelt die IP-Zuweisung und ermöglicht optional Netzwerk-Policies. Sie können es mit einem einfachen Terminalbefehl installieren:

kubectl apply -f https://docs.projectcalico.org/manifests/calico.yaml

Überprüfen Sie anschließend, ob alle Calico-Pods erfolgreich gestartet wurden:

kubectl get pods -n kube-system

Alle Pods sollten den Status Running oder Completed anzeigen. Falls Pods noch Pending zeigen, warten Sie ein paar Minuten, denn Calico benötigt eine Weile, um die Netzwerkkonfiguration auf allen Nodes zu verteilen.

Kubernetes unterstützt standardmäßig den Service-Typ Load Balancer, der externe IPs benötigt. In einem selbst-gehosteten Cluster wie auf Proxmox wird hierfür MetalLB verwendet. Installieren Sie zunächst MetalLB:

kubectl apply -f https://raw.githubusercontent.com/metallb/metallb/v0.13.10/config/manifests/metallb-native.yaml

Erstellen Sie anschließend einen IP-Pool, aus dem MetalLB IP-Adressen für Services vergeben kann. Passen Sie die IP-Range an Ihr lokales Netzwerk an:

cat <<EOF | kubectl apply -f -
apiVersion: metallb.io/v1beta1
kind: IPAddressPool
metadata:
name: my-ip-pool
namespace: metallb-system
spec:
addresses:
- 192.168.1.200-192.168.1.210
---
apiVersion: metallb.io/v1beta1
kind: L2Advertisement
metadata:
name: l2adv
namespace: metallb-system
spec: {}
EOF

Überprüfen Sie auch hier, ob die MetalLB-Pods korrekt laufen:

kubectl get pods -n metallb-system

Sobald alle Pods den Status Running haben, ist Ihr Netzwerk eingerichtet. Sie können nun Kubernetes-Services vom Typ LoadBalancer verwenden, um Anwendungen im LAN erreichbar zu machen. Damit ist Ihr Kubernetes-Proxmox-Cluster vollständig eingerichtet und bereit, Anwendungen zu deployen und Netzwerkressourcen zu verwalten.