K3s im Homelab: Dein erster Kubernetes-Cluster mit Proxmox

Moin zusammen und herzlich willkommen auf smoth.me! Als alter Hase im Homelab und bekennender Fan von Proxmox, Docker und allem, was man so virtualisieren oder containerisieren kann, freue ich mich, heute mal ein Thema anzugehen, das bei vielen auf dem Zettel steht, aber oft Respekt einflößt: Kubernetes im eigenen Homelab.

Wer sich mit Open-Source-Projekten beschäftigt, stößt unweigerlich auf Kubernetes. Es ist ein Gigant, ein Paradebeispiel dafür, wie eine riesige Community ein Projekt vorantreibt. Das Schöne daran: Die Konzepte, die Kubernetes so mächtig machen, lassen sich auch im Kleinen, also bei uns im Homelab, wunderbar anwenden. Ich rede hier nicht davon, einen Full-Blown-Produktionscluster mit etlichen Nodes und allem Schnickschnack aufzusetzen. Nein, mein Ziel für uns ist es, einen schlanken, aber voll funktionsfähigen Kubernetes-Cluster mit K3s auf unseren Proxmox-Servern zu realisieren.

In meiner Erfahrung ist K3s – die "Lightweight Kubernetes"-Distribution von Rancher – perfekt für diesen Zweck. Es ist ressourcenschonend, schnell installiert und bringt trotzdem alle Kernfunktionen von Kubernetes mit. Ideal, um die Konzepte zu verstehen, ohne gleich einen halben Server nur für die Control Plane zu verbraten. Ich habe das selbst schon mehrfach aufgesetzt, und die folgenden Schritte sind genau die, die ich jedes Mal gehe. Lass uns gemeinsam deinen ersten K3s-Cluster auf die Beine stellen!

Warum K3s für das Homelab?

Du fragst dich vielleicht, warum ich K3s und nicht das "große" Kubernetes empfehle. Ganz einfach: K3s ist für Edge-Computing und IoT optimiert, was es gleichzeitig zur perfekten Wahl für unser Homelab macht. Es ist ein einzelnes, kompaktes Binary, das alles Wichtige enthält. Das macht die Installation kinderleicht und den Ressourcenverbrauch minimal. Für uns bedeutet das:

Weniger Overhead: K3s verzichtet auf nicht benötigte Alpha-Features und Legacy-Komponenten.
Einfache Installation: Ein einziger Befehl, und der Server läuft.
Geringer Ressourcenverbrauch: Perfekt für VMs mit wenig RAM und CPU.
Volle Kubernetes-Kompatibilität: Deine YAML-Manifeste laufen hier genauso wie auf einem großen Cluster.

Wer das zum ersten Mal einrichtet, stolpert oft über die Komplexität von "echtem" Kubernetes. K3s nimmt dir hier viel Arbeit ab und lässt dich dich auf die Kubernetes-Konzepte konzentrieren, anstatt auf die Installation.

Voraussetzungen: Was du mitbringen solltest

Bevor wir loslegen, lass uns kurz checken, ob wir alles beisammenhaben. Keine Sorge, die Anforderungen sind überschaubar:

Hardware

Ein Proxmox VE Server, der genügend Ressourcen für mindestens zwei bis drei virtuelle Maschinen bereitstellen kann.
Empfehlung für die VMs:
- K3s Server (Control Plane): 2 vCPUs, 2 GB RAM, 20 GB Festplatte
- K3s Agent(s) (Worker Nodes): 1 vCPU, 1 GB RAM, 10 GB Festplatte (pro Node)

Software & Betriebssystem

Als Basis-Betriebssystem für die VMs empfehle ich Debian 11/12 (Bullseye/Bookworm) oder Ubuntu LTS (20.04/22.04). Ich persönlich nutze am liebsten Debian für meine Server, da es schlank und stabil ist.
SSH-Client auf deinem lokalen Rechner, um dich mit den VMs zu verbinden.

Netzwerk

Alle deine K3s-VMs sollten im gleichen Subnetz liegen und sich gegenseitig erreichen können.
Statische IP-Adressen sind ein absolutes Muss für alle K3s-Nodes. DHCP ist hier dein Feind, wenn es um Stabilität geht.
Stelle sicher, dass keine Firewall auf Proxmox-Ebene oder deinem Router den internen Datenverkehr zwischen den Nodes blockiert. K3s nutzt standardmäßig Ports wie 6443 (API Server), 10250 (Kubelet), 8472 (Flannel VXLAN) und 2379-2380 (Embedded etcd, falls du mehr als einen Control Plane Node hast).

Kenntnisse

Grundlagen im Umgang mit der Linux-Kommandozeile.
Basisverständnis von Netzwerktechnik (IP-Adressen, Subnetze).
Erfahrung mit Proxmox zur VM-Erstellung und -Verwaltung.

Wichtig zu wissen: Auch wenn wir hier mit K3s arbeiten, sind die Konzepte von Kubernetes universell. Wenn du K3s verstehst, verstehst du auch die Grundlagen von Kubernetes.

Schritt-für-Schritt-Anleitung: Dein K3s-Cluster entsteht

Jetzt wird's ernst! Wir werden zuerst die VMs auf Proxmox vorbereiten und dann K3s installieren. Ich gehe davon aus, dass du bereits einen Proxmox-Server am Laufen hast und dich mit der Erstellung von VMs auskennst.

1. Vorbereitung der VMs auf Proxmox

Erstelle für den Anfang zwei neue VMs auf deinem Proxmox-Server: eine für den K3s Server und eine für den K3s Agent. Wenn du später mehr Worker-Nodes brauchst, kannst du einfach weitere Agent-VMs hinzufügen.

VM-Name: z.B. k3s-server-01 und k3s-agent-01
OS-Typ: Linux, Debian oder Ubuntu Cloud-Image (oder Minimal-Installation)
System: QEMU Agent aktivieren (qemu-guest-agent in der VM installieren!)
Festplatte: Wie oben beschrieben, z.B. 20 GB für den Server, 10 GB für den Agent. NVMe oder SSD für bessere Performance.
CPU: 2 vCPUs für Server, 1 vCPU für Agent.
RAM: 2 GB für Server, 1 GB für Agent.
Netzwerk: Bridged-Modus (vmbr0 oder dein entsprechendes Bridge-Interface), damit die VMs direkt im Netzwerk deines Homelabs sind.

Nach der Installation des Betriebssystems auf beiden VMs logge dich per SSH ein und führe die üblichen Updates durch:

sudo apt update && sudo apt upgrade -y
sudo apt install -y curl vim git qemu-guest-agent
sudo systemctl enable qemu-guest-agent --now

Ganz wichtig: Konfiguriere statische IP-Adressen für beide VMs. Das ist entscheidend für die Stabilität des Clusters. Hier ein Beispiel für Debian/Ubuntu in /etc/network/interfaces oder /etc/netplan/*.yaml (je nach OS-Version):

# Beispiel fuer /etc/network/interfaces (Debian)
# Ersetze die Werte mit deinen Netzwerkeinstellungen
auto ens18
iface ens18 inet static
    address 192.168.1.100/24  # IP des K3s Servers
    gateway 192.168.1.1
    dns-nameservers 192.168.1.1 8.8.8.8

# Fuer den Agent entsprechend anpassen, z.B. 192.168.1.101

Nach der Netzwerkkonfiguration die VMs neu starten und überprüfen, ob die statischen IPs korrekt zugewiesen wurden und sie sich gegenseitig pingen können.

2. Installation des K3s Servers (Control Plane)

Jetzt kommt der spannende Teil! Wir installieren K3s auf der VM, die als Control Plane dienen soll (z.B. k3s-server-01). K3s bietet ein super einfaches Installationsskript an.

Verbinde dich per SSH mit deinem K3s Server und führe den folgenden Befehl aus:

curl -sfL https://get.k3s.io | sh -s -- --node-ip 192.168.1.100 --disable traefik --cluster-cidr 10.42.0.0/16 --service-cidr 10.43.0.0/16

Lass uns kurz die Parameter erklären:

curl -sfL https://get.k3s.io | sh -s: Lädt das offizielle Installationsskript herunter und führt es aus.
--node-ip 192.168.1.100: Ganz wichtig! Hier gibst du die statische IP-Adresse deines K3s Servers an. Das stellt sicher, dass K3s die richtige IP für interne Kommunikation und externe Anfragen nutzt.
--disable traefik: Traefik ist ein beliebter Ingress Controller, der standardmäßig mit K3s installiert wird. Für den Anfang, um die Dinge einfach zu halten, deaktiviere ich ihn oft. Später kannst du ihn aktivieren oder einen anderen wie NGINX Ingress Controller installieren.
--cluster-cidr 10.42.0.0/16: Definiert den CIDR-Bereich für die Pod-IPs.
--service-cidr 10.43.0.0/16: Definiert den CIDR-Bereich für die Service-IPs.

Das Skript installiert K3s, startet die Dienste und konfiguriert systemd. Nach wenigen Momenten sollte K3s laufen.

Um später mit dem Cluster interagieren zu können, benötigst du die kubeconfig-Datei. Diese findest du auf dem Server unter /etc/rancher/k3s/k3s.yaml.

Kopiere diese Datei auf deinen lokalen Rechner. Ich nutze dafür gerne scp:

scp user@192.168.1.100:/etc/rancher/k3s/k3s.yaml ~/.kube/config-k3s

Mein Tipp: Benenne die Datei um (z.B. config-k3s), damit sie nicht deine Standard-kubeconfig überschreibt. Du kannst dann mit export KUBECONFIG=~/.kube/config-k3s oder der --kubeconfig-Option in kubectl darauf zugreifen.

Bevor wir Agents hinzufügen, können wir schon mal den Status des Servers prüfen:

# Auf dem K3s Server ausfuehren
sudo kubectl get nodes
sudo kubectl get pods -A

Du solltest sehen, dass ein Node (dein Server) im Status Ready ist und einige System-Pods laufen.

3. Hinzufügen von K3s Agents (Worker Nodes)

Ein Kubernetes-Cluster wird erst richtig nützlich, wenn er Worker Nodes hat, die die eigentliche Arbeit erledigen. Wir fügen nun unseren K3s Agent (z.B. k3s-agent-01) zum Cluster hinzu.

Zuerst benötigen wir das K3s-Join-Token vom Server. Das findest du in der Datei /var/lib/rancher/k3s/server/node-token auf deinem K3s Server:

# Auf dem K3s Server ausfuehren
sudo cat /var/lib/rancher/k3s/server/node-token

Kopiere dir diesen Token. Er sieht in etwa so aus: K10ccbe646271c0d487f94017f8582d1c68d1a6d71c08d246c0d6a0d4212345678::server:a1b2c3d4e5f6g7h8.

Jetzt verbinde dich per SSH mit deinem K3s Agent (z.B. k3s-agent-01) und führe den Installationsbefehl aus:

curl -sfL https://get.k3s.io | K3S_URL=https://192.168.1.100:6443 K3S_TOKEN="DEIN_TOKEN_HIER" sh -s -- --node-ip 192.168.1.101

Erklärung der Parameter:

K3S_URL=https://192.168.1.100:6443: Hier gibst du die URL deines K3s Servers an. Wichtig ist die IP-Adresse des Servers und der Port 6443.
K3S_TOKEN="DEIN_TOKEN_HIER": Füge hier den Token ein, den du gerade vom Server kopiert hast.
--node-ip 192.168.1.101: Die statische IP-Adresse deines K3s Agents.

Nachdem das Skript durchgelaufen ist, sollte der Agent versuchen, sich mit dem Server zu verbinden. Das kann einen Moment dauern.

4. Cluster-Status überprüfen

Kehre zu deinem lokalen Rechner zurück (oder logge dich auf dem K3s Server ein) und nutze kubectl, um den Status deines Clusters zu überprüfen:

# Auf deinem lokalen Rechner (wenn kubeconfig kopiert wurde)
export KUBECONFIG=~/.kube/config-k3s
kubectl get nodes

Du solltest nun beide Nodes (Server und Agent) im Status Ready sehen:

NAME            STATUS   ROLES                  AGE    VERSION
k3s-server-01   Ready    control-plane,master   15m    v1.28.x+k3s1
k3s-agent-01    Ready    <none>                 2m     v1.28.x+k3s1

Glückwunsch! Du hast deinen ersten K3s-Cluster im Homelab erfolgreich aufgesetzt!

5. Ein erster Test: Dein erster Nginx-Deployment

Was wäre ein Kubernetes-Cluster ohne eine laufende Anwendung? Lass uns einen einfachen Nginx-Deployment erstellen.

Erstelle eine Datei namens nginx-deployment.yaml auf deinem lokalen Rechner:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
  labels:
    app: nginx
spec:
  replicas: 2
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:latest
        ports:
        - containerPort: 80
---
apiVersion: v1
kind: Service
metadata:
  name: nginx-service
spec:
  selector:
    app: nginx
  ports:
    - protocol: TCP
      port: 80
      targetPort: 80
  type: NodePort # Oder LoadBalancer, wenn ein K3s LoadBalancer Controller installiert ist (z.B. Kube-VIP)

Wende dieses Manifest auf deinen Cluster an:

kubectl apply -f nginx-deployment.yaml

Überprüfe den Status des Deployments und des Services:

kubectl get deployments
kubectl get pods -o wide
kubectl get services

Du solltest sehen, dass zwei Nginx-Pods laufen und ein Service namens nginx-service erstellt wurde. Da wir NodePort gewählt haben, kannst du Nginx über die IP-Adresse deiner Worker Nodes und den zugewiesenen NodePort erreichen (z.B. http://192.168.1.101:3xxxx).

Mein Tipp: Wenn du Traefik nicht deaktiviert hast, könntest du stattdessen einen Ingress für Nginx erstellen, um ihn über einen Hostnamen zu erreichen.

Häufige Fehler und Lösungen

Beim Einrichten eines Clusters kann immer mal was schiefgehen. Hier sind ein paar typische Stolpersteine, über die ich selbst schon gestolpert bin, und wie du sie beheben kannst:

1. Firewall-Probleme

Symptom: Nodes können sich nicht verbinden, Pods bleiben im Status Pending oder ContainerCreating, oder Services sind nicht erreichbar.
Ursache: Die Firewall auf den VMs (z.B. UFW) oder auf dem Proxmox-Host blockiert benötigte Ports.
Lösung:
- Deaktiviere testweise die Firewall auf den VMs (sudo ufw disable) oder konfiguriere sie korrekt.
- Stelle sicher, dass folgende Ports auf den K3s Server und Agenten offen sind (mindestens intern):
  - K3s Server: 6443 (Kubernetes API), 2379-2380 (etcd), 8472 (Flannel VXLAN), 10250 (Kubelet), 9345 (K3s Server Agent Kommunikation)
  - K3s Agent: 8472 (Flannel VXLAN), 10250 (Kubelet)
- Prüfe auch die Proxmox-Firewall, falls du diese aktiviert hast.

2. Netzwerkprobleme (IP-Adressen, DNS)

Symptom: Nodes bleiben NotReady, Pods können keine Images herunterladen oder sich nicht untereinander erreichen.
Ursache: Falsch konfigurierte statische IP-Adressen, DNS-Probleme oder IP-Adresskonflikte.
Lösung:
- Überprüfe die --node-ip-Parameter bei der Installation. Sie müssen exakt den statischen IPs deiner VMs entsprechen.
- Stelle sicher, dass die Nodes sich gegenseitig pingen können (ping ).
- Überprüfe die DNS-Einstellungen in /etc/resolv.conf oder deiner Netzwerkkonfiguration. Pods müssen in der Lage sein, externe Repositories (z.B. Docker Hub) aufzulösen.
- Vermeide DHCP für K3s-Nodes; statische IPs sind hier der Goldstandard.

3. K3s-Token-Probleme

Symptom: K3s Agents können dem Cluster nicht beitreten und zeigen Fehlermeldungen wie "Failed to connect to K3s server".
Ursache: Falscher oder abgelaufener K3s-Token, oder falsche K3S_URL.
Lösung:
- Überprüfe nochmals den Token auf dem Server (sudo cat /var/lib/rancher/k3s/server/node-token) und stelle sicher, dass du ihn exakt kopiert hast.
- Kontrolliere die K3S_URL. Sie muss auf die korrekte IP-Adresse des K3s Servers und den Port 6443 zeigen (https://:6443).
- Wenn der Token aus irgendeinem Grund nicht funktioniert, kannst du einen neuen generieren (was aber den Cluster temporär beeinflussen kann) oder den K3s Server neu installieren, um einen frischen Token zu erhalten. Für Homelabs ist das oft der einfachste Weg.

4. Ressourcenmangel

Symptom: Nodes werden langsam, Pods starten nicht, oder der K3s-Server stürzt ab.
Ursache: Zu wenig RAM oder CPU für die VMs.
Lösung:
- Erhöhe RAM und CPU der betroffenen VMs in Proxmox. Meine oben genannten Empfehlungen sind ein Minimum, besonders wenn du viele Pods oder ressourcenintensive Anwendungen betreiben willst.
- Überwache die Ressourcen deiner VMs mit Tools wie htop oder free -h.

Wenn du in Schwierigkeiten gerätst, schau immer zuerst in die Logs des K3s-Dienstes auf den betroffenen Nodes:

sudo journalctl -u k3s --no-pager
sudo journalctl -u k3s-agent --no-pager # Auf Agent-Nodes

Die Fehlermeldungen dort sind oft sehr aufschlussreich!

Fazit und Nächste Schritte

Puh, das war ein Ritt! Aber jetzt hast du einen voll funktionsfähigen K3s-Kubernetes-Cluster in deinem Homelab. Du hast nicht nur die VMs vorbereitet und K3s installiert, sondern auch schon deine erste Anwendung – einen Nginx-Deployment – gestartet. Das ist ein fantastischer Startpunkt, um tiefer in die Welt von Kubernetes einzutauchen.

Was sind die nächsten Schritte? Hier ein paar Ideen, die ich dir ans Herz legen kann:

Ingress Controller: Wenn du Traefik deaktiviert hast, installiere einen Ingress Controller wie NGINX Ingress Controller. Damit kannst du deine Anwendungen über Hostnamen und Port 80/443 von außen erreichbar machen.
Persistent Storage: Für zustandsbehaftete Anwendungen (Datenbanken, etc.) benötigst du persistenten Speicher. Schau dir Lösungen wie Longhorn (ebenfalls von Rancher, super für Homelabs) oder OpenEBS an.
Monitoring: Setze ein Monitoring-Stack auf, z.B. mit Prometheus und Grafana, um deinen Cluster und deine Anwendungen im Blick zu behalten.
CI/CD: Integriere deinen Cluster in eine CI/CD-Pipeline, um automatische Deployments zu ermöglichen. Tools wie GitLab CI/CD oder Argo CD sind hier super.
Weitere Anwendungen: Experimentiere mit anderen Anwendungen, die du in deinem Homelab betreiben möchtest – von Home Assistant bis zu N8N oder einer Nextcloud-Instanz.

Die Welt von Kubernetes ist riesig, aber mit diesem K3s-Setup hast du eine solide Basis geschaffen, um sie zu erkunden. Hab Spaß beim Experimentieren und vergiss nicht: Im Homelab darf man Fehler machen, daraus lernt man am meisten!