Ku­ber­netes-Cluster auf Proxmox erstellen: Schritt-für-Schritt-Anleitung

Die Er­stel­lung eines Ku­ber­netes-Clusters auf Proxmox er­mög­licht es Ihnen, in einer vir­tua­li­sier­ten und selbst ge­hos­te­ten Umgebung eine per­for­man­te Container-Or­ches­trie­rungs­platt­form zu betreiben. Diese ist ideal für Test­um­ge­bun­gen, Ent­wick­lungs- und CI-Workflows oder auch kleinere Pro­duk­ti­ons­sze­na­ri­en. In dieser Anleitung erfahren Sie Schritt für Schritt, wie Sie auf Proxmox virtuelle Maschinen ein­rich­ten und daraus ein stabiles Ku­ber­netes-Cluster aufbauen.

Schritt 1: Vor­aus­set­zun­gen prüfen

Bevor Sie mit der ei­gent­li­chen Ein­rich­tung des Ku­ber­netes-Clusters beginnen, sollten Sie si­cher­stel­len, dass Ihre Umgebung alle tech­ni­schen Vor­aus­set­zun­gen erfüllt. Eine saubere Aus­gangs­ba­sis erspart später viel Zeit und vermeidet Kon­fi­gu­ra­ti­ons­feh­ler.

Sie benötigen zunächst eine funk­tio­nie­ren­de Proxmox VE-In­stal­la­ti­on. Aus Leis­tungs­grün­den empfiehlt sich eine Bare-Metal-In­stal­la­ti­on von Proxmox. Sowohl der Web-Zugang über die Proxmox-Ober­flä­che als auch der SSH-Zugang zur Kom­man­do­zei­le sollten verfügbar sein. Über SSH können Sie Befehle ausführen, Images hochladen und Kon­fi­gu­ra­tio­nen au­to­ma­ti­sie­ren.

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

• ein Master-Node (für die so­ge­nann­te Control Plane) und
• min­des­tens zwei Worker-Nodes.

Damit erreichen Sie eine gewisse Redundanz und können Ku­ber­netes so betreiben, wie es in echten Pro­duk­ti­ons­um­ge­bun­gen vor­ge­se­hen ist. Für Test­zwe­cke genügt jedoch auch ein kleineres Setup mit einem Master und einem Worker.

Ihr Proxmox-Host sollte außerdem über eine funk­tio­nie­ren­de Bridge-Schnitt­stel­le verfügen, die den vir­tu­el­len Maschinen den Zugang ins lokale Netzwerk und ggf. ins Internet er­mög­licht. Das ist wichtig, damit die VMs später Updates her­un­ter­la­den und Ku­ber­netes-Kom­po­nen­ten in­stal­lie­ren können.

Schritt 2: Cloud-Image her­un­ter­la­den und als Template vor­be­rei­ten

Ku­ber­netes-In­stal­la­tio­nen lassen sich am ein­fachs­ten mit so­ge­nann­ten Cloud-Images durch­füh­ren. Diese vor­kon­fi­gu­rier­ten Be­triebs­sys­tem-Images, meist Ubuntu oder Debian, sind für den au­to­ma­ti­schen Start mit cloud-init optimiert. Wir verwenden in diesem Beispiel ein Ubuntu 22.04 LTS Cloud-Image, da es stabil, gut do­ku­men­tiert und optimal für den Einsatz mit Ku­ber­netes 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 Ver­zeich­nis, in dem Proxmox ISO- und Image-Dateien speichert:

cd /var/lib/vz/template/iso

Laden Sie an­schlie­ß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 ein­deu­ti­gen ID, zum Beispiel 9000, und weisen Sie ihr grund­le­gen­de Hardware-Res­sour­cen zu:

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

Nun im­por­tie­ren Sie das zuvor her­un­ter­ge­la­de­ne Cloud-Image als virtuelle Fest­plat­te in den ge­wünsch­ten Speicher (in unserem Beispiel local-lvm):

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

An­schlie­ßend können Sie die im­por­tier­te Fest­plat­te mit der VM verbinden und den richtigen Con­trol­ler ein­stel­len. Auf diese Weise wird das Image an den vir­tu­el­len SCSI-Con­trol­ler der vir­tu­el­len Maschine gebunden:

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

Damit Sie später beim Klonen der VMs au­to­ma­tisch 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 au­to­ma­tisch an­ge­wen­de­ten Kon­fi­gu­ra­ti­ons­da­ten. Fügen Sie das Cloud-Init-Drive hinzu und de­fi­nie­ren Sie die Boot­rei­hen­fol­ge mit folgenden Befehlen:

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

Ak­ti­vie­ren Sie zu­sätz­lich den QEMU Guest Agent, damit Proxmox später Sta­tus­in­for­ma­tio­nen aus der VM auslesen kann, und kon­fi­gu­rie­ren 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 ein­ge­rich­tet ist, können Sie Ihre virtuelle Maschine in ein so­ge­nann­tes 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 Ku­ber­netes-Nodes.

qm template 9000

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

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

In einem dritten Schritt erstellen Sie aus dem zuvor an­ge­leg­ten Template die vir­tu­el­len Maschinen, die später als Master- und Worker-Knoten Ihres Ku­ber­netes-Clusters dienen. Jede dieser VMs erhält eine eigene IP-Adresse, einen ein­deu­ti­gen Hostnamen sowie einen SSH-Schlüssel für den sicheren Zugriff. Proxmox übernimmt die Grund­kon­fi­gu­ra­ti­on au­to­ma­tisch über cloud-init, sodass Sie keine manuelle Ein­rich­tung mehr innerhalb der vir­tu­el­len Maschinen durch­füh­ren 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 ent­spre­chen­den Worker-Knoten. Dabei können Sie CPU und Ar­beits­spei­cher in­di­vi­du­ell 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

An­schlie­ßend de­fi­nie­ren Sie über cloud-init die grund­le­gen­den Netz­werk­ein­stel­lun­gen, 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 un­ten­ste­hen­den Ter­mi­nal­be­feh­len:

qm start 101
qm start 102
qm start 103

Warten Sie einen Moment, bis die Systeme voll­stän­dig hoch­ge­fah­ren sind, und testen Sie dann die Ver­bin­dung per SSH. Wenn alles funk­tio­niert, können Sie sich bei­spiels­wei­se mit folgendem Befehl auf dem Master-Knoten anmelden:

ssh ubuntu@192.168.1.10

Schritt 4: Basis-Kon­fi­gu­ra­ti­on auf allen vir­tu­el­len Maschinen hin­zu­fü­gen

Bevor Sie Ku­ber­netes auf den VMs in­stal­lie­ren, sollten Sie einige sys­tem­wei­te Ein­stel­lun­gen vornehmen, die für den stabilen Betrieb er­for­der­lich sind. Dazu gehören das De­ak­ti­vie­ren von Swap, das Anpassen von Kernel-Pa­ra­me­tern für Netzwerk und IP-For­war­ding sowie die Syn­chro­ni­sa­ti­on der Sys­tem­zeit. Diese Maßnahmen sorgen dafür, dass Ku­ber­netes korrekt arbeiten kann und Netz­werk­funk­tio­nen innerhalb der Container zu­ver­läs­sig funk­tio­nie­ren.

Zunächst de­ak­ti­vie­ren Sie Swap auf allen Nodes, da Ku­ber­netes dies für die Scheduler-Logik verlangt. Außerdem entfernen Sie den ent­spre­chen­den Eintrag in /etc/fstab, damit Swap nach einem Neustart nicht erneut aktiviert wird:

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

An­schlie­ßend kon­fi­gu­rie­ren Sie die Kernel-Parameter, um si­cher­zu­stel­len, dass Netz­werk­pa­ke­te zwischen Con­tai­nern und Knoten korrekt ver­ar­bei­tet 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 Syn­chro­ni­sa­ti­on der Sys­tem­zeit, damit Zer­ti­fi­ka­te und Cluster-Kom­po­nen­ten keine Probleme aufgrund ab­wei­chen­der Zeiten ver­ur­sa­chen. Dazu können Sie chrony in­stal­lie­ren und starten:

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

Schließ­lich empfiehlt es sich, einige grund­le­gen­de Hilfs­pro­gram­me zu in­stal­lie­ren, 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 ein­heit­lich vor­be­rei­tet, Swap ist de­ak­ti­viert, die Netz­werk­ein­stel­lun­gen sind korrekt gesetzt und die Zeit syn­chro­ni­siert. Ihre VMs sind nun bereit für die In­stal­la­ti­on von Ku­ber­netes und den Aufbau Ihres Clusters.

Schritt 5: Wahl der Ku­ber­netes-Dis­tri­bu­ti­on

Bevor Sie mit der ei­gent­li­chen In­stal­la­ti­on von Ku­ber­netes beginnen, sollten Sie sich für eine passende Dis­tri­bu­ti­on ent­schei­den. Auf Basis Ihrer An­for­de­run­gen können Sie zwischen zwei emp­feh­lens­wer­ten Varianten wählen:

• RKE2 (Rancher Ku­ber­netes Engine 2): RKE2 ist eine stabile, pro­duc­tion-ready Ku­ber­netes-Dis­tri­bu­ti­on, die von Rancher ent­wi­ckelt wird. Sie eignet sich besonders, wenn Sie später eine grafische Ver­wal­tung über Rancher nutzen möchten oder ein Cluster mit mehreren Control-Plane-Nodes planen.
• k3s: k3s ist eine schlanke Ku­ber­netes-Dis­tri­bu­ti­on, die ideal für Test­um­ge­bun­gen, Home-Labs oder res­sour­cen­be­grenz­te Systeme ist. Sie ist sehr einfach zu in­stal­lie­ren und benötigt weniger Speicher und CPU.

Für den Aufbau eines robusten Ku­ber­netes-Clusters auf Proxmox, das auch in einem pro­duk­ti­ons­na­hen Szenario betrieben werden könnte, empfiehlt sich RKE2. Wenn Sie jedoch schnell ein kleines Test- oder Ent­wick­lungs­clus­ter ein­rich­ten möchten, ist k3s die prak­ti­sche­re Al­ter­na­ti­ve. Im weiteren Verlauf dieser Anleitung wird RKE2 genutzt.

Schritt 6: RKE2 auf dem Master in­stal­lie­ren

Nachdem die Basis-Kon­fi­gu­ra­ti­on Ihrer vir­tu­el­len Maschinen ab­ge­schlos­sen ist, können Sie mit der In­stal­la­ti­on 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-In­stal­la­ti­ons­skript herunter und führen Sie es aus. Dabei können Sie optional einen Kanal mit der ge­wünsch­ten Version angeben:

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

Nach der In­stal­la­ti­on ak­ti­vie­ren Sie den RKE2-Ser­ver­dienst und starten ihn sofort:

sudo systemctl enable --now rke2-server.service

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

sudo systemctl status rke2-server

Um das Ku­ber­netes-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

An­schlie­ß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 er­reich­bar ist:

kubectl get nodes

Wenn der Master angezeigt wird, ist die In­stal­la­ti­on er­folg­reich ab­ge­schlos­sen und Sie können im nächsten Schritt die Worker-Knoten hin­zu­fü­gen.

Schritt 7: RKE2-Agent auf den Worker-Knoten in­stal­lie­ren

Nachdem der Master-Knoten er­folg­reich ein­ge­rich­tet wurde, können Sie nun die Worker-Knoten in Ihr Cluster in­te­grie­ren. Dazu in­stal­lie­ren 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 Au­then­ti­fi­zie­rung der Worker beim Cluster er­for­der­lich 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 In­stal­la­ti­ons­skript für RKE2 herunter und in­stal­lie­ren Sie den Agenten mit folgendem Befehl:

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

Erstellen Sie an­schlie­ßend die Kon­fi­gu­ra­ti­ons­da­tei 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
token: <TOKEN_HIER_EINFÜGEN>
EOF

Ab­schlie­ßend ak­ti­vie­ren und starten Sie den RKE2-Agent-Dienst:

sudo systemctl enable --now rke2-agent.service

Wie­der­ho­len Sie diesen Vorgang für alle Worker-Knoten im Cluster. Nach einigen Minuten können Sie auf dem Master über­prü­fen, ob die Worker-Knoten korrekt verbunden sind:

kubectl get nodes

Sie sollten nun alle Nodes sehen, den Master sowie die neu hin­zu­ge­füg­ten Worker. Damit ist Ihr Cluster voll­stän­dig und bereit für die In­stal­la­ti­on von Netzwerk-Plugins, Load Balancer und weiteren Ku­ber­netes-Kom­po­nen­ten.

Schritt 8: Netzwerk-CNI und Load­Ba­lan­cer in­stal­lie­ren

Nachdem Master- und Worker-Knoten er­folg­reich ein­ge­rich­tet sind, benötigen Sie ein Container Network Interface (CNI), damit die Pods im Cluster mit­ein­an­der kom­mu­ni­zie­ren können, sowie einen Load Balancer, um Services im Netzwerk er­reich­bar zu machen. In dieser Anleitung verwenden wir Calico als CNI und MetalLB für die Layer-2-Load-Balancing-Funk­tio­na­li­tät.

Calico stellt die Netz­werk­ver­bin­dun­gen zwischen den Pods her, regelt die IP-Zuweisung und er­mög­licht optional Netzwerk-Policies. Sie können es mit einem einfachen Ter­mi­nal­be­fehl in­stal­lie­ren:

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

Über­prü­fen Sie an­schlie­ßend, ob alle Calico-Pods er­folg­reich 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 Netz­werk­kon­fi­gu­ra­ti­on auf allen Nodes zu verteilen.

Ku­ber­netes un­ter­stützt stan­dard­mä­ßig den Service-Typ Load Balancer, der externe IPs benötigt. In einem selbst-ge­hos­te­ten Cluster wie auf Proxmox wird hierfür MetalLB verwendet. In­stal­lie­ren Sie zunächst MetalLB:

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

Erstellen Sie an­schlie­ß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

Über­prü­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 ein­ge­rich­tet. Sie können nun Ku­ber­netes-Services vom Typ Load­Ba­lan­cer verwenden, um An­wen­dun­gen im LAN er­reich­bar zu machen. Damit ist Ihr Ku­ber­netes-Proxmox-Cluster voll­stän­dig ein­ge­rich­tet und bereit, An­wen­dun­gen zu deployen und Netz­werk­res­sour­cen zu verwalten.