K3S installieren: Single-Node und Multi-Node Cluster – Schritt für Schritt

Der größte Vorteil von K3S zeigt sich genau an dieser Stelle: Während die Installation eines Standard-Kubernetes-Clusters Stunden dauern kann und etliche Einzelschritte erfordert, ist K3S in wenigen Minuten einsatzbereit. Ein einziger Befehl genügt – und der gesamte Kubernetes-Control-Plane läuft. Doch so einfach die Installation auch ist, es gibt einige Details, die den Unterschied zwischen einer funktionierenden Lab-Umgebung und einem produktionsreifen Cluster ausmachen.

In dieser Anleitung installieren wir K3S sowohl als Single-Node-Cluster für Entwicklung und Tests als auch als Multi-Node-Cluster mit Server- und Agent-Nodes für produktivere Umgebungen. Jeder Schritt wird erklärt, damit Sie verstehen, was passiert – und damit Sie wissen, wo Sie eingreifen können, wenn etwas nicht funktioniert.

Voraussetzungen: Was Sie vor der Installation benötigen

Bevor wir mit der Installation beginnen, stellen wir sicher, dass die Grundvoraussetzungen erfüllt sind. K3S ist bemerkenswert genügsam, was die Hardware angeht – aber einige Mindestanforderungen sollten Sie dennoch beachten.

Hardware-Anforderungen

Komponente	Minimum	Empfohlen
CPU	1 Core	2+ Cores
RAM (Server)	512 MB	1 GB+
RAM (Agent)	256 MB	512 MB+
Festplatte	8 GB freier Speicher	20 GB+
Betriebssystem	Ubuntu 20.04+, Debian 11+, Rocky Linux 8+, openSUSE 15.4+	Ubuntu 22.04 LTS oder 24.04 LTS
Netzwerk	Internet-Zugang (für Installation)	Statische IP, offene Ports 6443, 10250, 8472

K3S läuft auf nahezu jeder Linux-Distribution, die systemd als Init-System verwendet. Die beiden beliebtesten Plattformen sind Ubuntu Server und Rocky Linux / Alma Linux – beide bieten Long-Term-Support und sind in Unternehmen weit verbreitet. Für produktive Umgebungen empfehle ich Ubuntu 22.04 LTS oder 24.04 LTS als Basis-System.

Ports und Firewall

K3S kommuniziert über eine Reihe von Ports, die im Netzwerk freigegeben sein müssen. Wenn eine Firewall aktiv ist – etwa ufw auf Ubuntu oder firewalld auf Rocky Linux – müssen folgende Ports geöffnet werden:

Port	Protokoll	Richtung	Zweck
6443	TCP	inbound (Agent → Server)	Kubernetes API Server
10250	TCP	bidirektional	Kubelet Metrics API
8472	UDP	bidirektional	Flannel VXLAN Overlay Network
2379	TCP	Server → Server	etcd Client Port
2380	TCP	Server → Server	etcd Peer Port
30000–32767	TCP	inbound	NodePort Services (falls benötigt)

Für einen Single-Node-Cluster, bei dem Server und Agent auf demselben Host laufen, ist keine Firewall-Konfiguration notwendig – alle Ports werden lokal bedient. Sobald Sie jedoch Agent-Nodes auf separaten Maschinen betreiben, müssen die oben genannten Ports zwischen allen Nodes frei sein.

Netzwerkanforderungen

Stellen Sie sicher, dass jeder Node über eine statische IP-Adresse verfügt. DHCP-basierte Adressen können funktionieren, sind in Produktivumgebungen jedoch problematisch, da eine wechselnde IP-Adresse den Cluster unterbrechen kann.

Achten Sie auch darauf, dass die Server- und Agent-Nodes sich gegenseitig über die jeweiligen IP-Adressen erreichen können. K3S nutzt für die interne Kommunikation das Flannel-Overlay-Netzwerk, das auf UDP-Port 8472 arbeitet. Dieser Port ist in vielen Firewall-Konfigurationen standardmäßig gesperrt.

Single-Node-Installation: K3S als All-in-One-Server

Die Single-Node-Installation ist der schnellste Weg zu einem funktionierenden Kubernetes-Cluster. In diesem Setup fungiert der K3S-Server gleichzeitig als Control Plane und als Worker – alle Kubernetes-Komponenten laufen auf einem einzigen Host.

Diese Konfiguration eignet sich ideal für:

• lokale Entwicklungsumgebungen
• Tests und Proof-of-Concepts
• kleine Edge-Installationen
• CI/CD-Pipelines mit kurzlebigen Kubernetes-Clustern

Schritt 1: System aktualisieren

Bevor wir K3S installieren, aktualisieren wir das Betriebssystem und installieren die grundlegenden Abhängigkeiten:

1
sudo apt update && sudo apt upgrade -y

Dieser Schritt stellt sicher, dass alle Sicherheitsupdates eingespielt sind und die Basisumgebung aktuell ist. Je nach Installationszeitpunkt kann dieser Vorgang einige Minuten dauern.

Schritt 2: K3S installieren

Die Installation erfolgt über das offizielle K3S-Installationsskript. Der Installer lädt das K3S-Binärfile herunter, richtet es als systemd-Dienst ein und startet den Server automatisch:

1
curl -sfL https://get.k3s.io | sh -

Das Skript erkennt automatisch das Betriebssystem, lädt die passende Version herunter und richtet den Dienst ein. Nach erfolgreicher Ausführung erhalten Sie eine Ausgabe, die in etwa so aussieht:

1
2
3
4
5
6
7
8
[INFO]  Finding release for channel stable

[INFO]  Using v1.31.1+k3s2 as release

[INFO]  Downloading hash https://github.com/k3s-io/k3s/releases/download/v1.31.1+k3s2/sha256sum.txt

[INFO]  Downloading K3s v1.31.1+k3s2 from https://github.com/k3s-io/k3s/releases/download/v1.31.1+k3s2/k3s

[INFO]  Verifying binary checksum

[INFO]  Installing K3s to /usr/local/bin/k3s

[INFO]  Skipping https://get.k3s.io/setup.sh download, already cached locally

[INFO]  Starting k3s

Der Installer hat den K3S-Server als systemd-Dienst eingerichtet und automatisch gestartet. Das bedeutet: K3S überlebt auch einen Neustart des Servers – ohne dass Sie eingreifen müssen.

Schritt 3: Node-Token sichern

Nach der Installation wird ein sogenanntes Node-Token generiert. Dieser Token wird benötigt, um weitere Agent-Nodes zum Cluster hinzuzufügen. Bewahren Sie ihn sicher auf:

1
sudo cat /var/lib/rancher/k3s/server/node-token

Die Ausgabe sieht in etwa so aus:

1
K104f3a2c7d4e5f678901234567890abcdefghijk1234567lmno::server:abcdef1234567890

Kopieren Sie diesen Token an einen sicheren Ort. Sie benötigen ihn im nächsten Abschnitt, wenn Sie Agent-Nodes zum Cluster hinzufügen möchten. In einer Produktivumgebung sollte dieser Token wie ein Passwort behandelt werden – er gewährt Zugriff auf Ihren Cluster.

Schritt 4: Cluster-Status prüfen

K3S bringt kubectl bereits mit. Die kubeconfig-Datei liegt unter

. Um den Cluster-Status zu prüfen, verwenden wir kubectl mit dem lokalen kubeconfig:

1
sudo k3s kubectl get nodes

Die Ausgabe zeigt den aktuellen Node-Status:

1
2
NAME        STATUS   ROLES           AGE     VERSION

k3s-server  Ready    control-plane   2m12s   v1.31.1+k3s2

Der Node ist bereit und als Control Plane markiert. Das bedeutet: Der Cluster ist funktionsfähig. Sie können nun Kubernetes-Workloads deployen, Helm-Charts installieren und die gesamte Kubernetes-API nutzen.

Um den Befehl ohne

und ohne den langen kubeconfig-Pfad ausführen zu können, richten wir einen Alias ein:

1
2
3
4
5
mkdir -p ~/.kube

sudo k3s kubectl config view --raw > ~/.kube/config

chmod 600 ~/.kube/config

echo 'export KUBECONFIG=~/.kube/config' >> ~/.bashrc

source ~/.bashrc

Ab sofort können Sie kubectl ohne sudo und ohne Pfad-Präfix verwenden:

1
2
kubectl get nodes

kubectl get pods -A

Schritt 5: Ersten Workload deployen

Um zu验证, dass der Cluster wirklich funktioniert, deployen wir einen einfachen Nginx-Webserver als Test-Workload:

1
2
kubectl create deployment nginx --image=nginx

kubectl expose deployment nginx --port=80 --type=LoadBalancer

Prüfen Sie den Status des Deployments:

1
kubectl get all

Alle Ressourcen sollten den Status „Running“ bzw. „Ready“ anzeigen. Der LoadBalancer-Service weist dem Nginx-Pod eine externe IP zu – in einer lokalen Umgebung ist dies typischerweise die IP des K3S-Hosts auf einem zufälligen Port im Bereich 30000–32767.

Mit diesem Test-Deployment haben Sie die Kernfunktionalität des Clusters verifiziert: Container-Runtime funktioniert, Networking funktioniert, die Kubernetes-API ist erreichbar.

Multi-Node-Installation: Server um Agent-Nodes erweitern

Ein Single-Node-Cluster ist für Entwicklung und Tests ideal. Für Produktivumgebungen empfiehlt sich jedoch ein Multi-Node-Setup, bei dem die Control-Plane-Komponenten auf dedizierten Server-Nodes laufen und die Workloads auf separaten Agent-Nodes ausgeführt werden.

In diesem Abschnitt erweitern wir den bestehenden Single-Node-Cluster um einen oder mehrere Agent-Nodes. Die Architektur sieht dann so aus:

• K3S Server (Control Plane): Verwaltet den Cluster-Zustand über die eingebettete etcd-Datenbank. Verarbeitet API-Anfragen und plant Workloads.
• K3S Agent (Worker): Führt Container aus, reportet Metriken an den Server, empfängt Deployments und führt diese aus.

Voraussetzungen für Agent-Nodes

Jeder Agent-Node muss folgende Voraussetzungen erfüllen:

• Linux-System mit systemd (Ubuntu, Debian, Rocky Linux, Alma Linux)
• Netzwerkverbindung zum K3S-Server (Port 6443, 8472 UDP)
• CPU: mindestens 1 Core (empfohlen: 2+)
• RAM: mindestens 512 MB (empfohlen: 1 GB+)
• Der Node-Token vom K3S-Server

Die Agent-Nodes müssen keine identischen Betriebssysteme haben wie der Server – K3S ist diesbezüglich flexibel. Solange das Betriebssystem systemd verwendet, sollte die Installation funktionieren. In der Praxis empfiehlt es sich jedoch, homogene Betriebssystemversionen zu verwenden, um potenzielle Kompatibilitätsprobleme zu vermeiden.

Schritt 1: Firewall auf dem Server anpassen

Bevor die Agent-Nodes hinzugefügt werden können, müssen die notwendigen Ports auf dem Server geöffnet sein. Bei einer UFW-Firewall auf Ubuntu beispielsweise:

1
2
3
4
5
6
sudo ufw allow 6443/tcp

sudo ufw allow 8472/udp

sudo ufw allow 10250/tcp

sudo ufw allow 2379/tcp

sudo ufw allow 2380/tcp

sudo ufw reload

Stellen Sie sicher, dass die Firewall auch eingehende Verbindungen von den IP-Bereichen Ihrer Agent-Nodes zulässt. In einer Produktivumgebung empfiehlt es sich, nur die notwendigen Ports zu öffnen und die Quell-IPs so weit wie möglich einzuschränken.

Schritt 2: Agent installieren

Auf jedem Agent-Node führen Sie die folgende Installation durch. Ersetzen Sie dabei

durch die IP-Adresse Ihres K3S-Servers und durch den Token, den Sie in Schritt 3 der Single-Node-Installation gesichert haben:

1
curl -sfL https://get.k3s.io | K3S_URL=https://<server-ip>:6443 K3S_TOKEN=<node-token> sh -

Das Installationsskript lädt den K3S-Agent herunter, richtet ihn als systemd-Dienst ein und startet ihn automatisch. Der Agent registriert sich beim Server und beginnt, Heartbeats zu senden.

Schritt 3: Agent-Registrierung prüfen

Auf dem K3S-Server prüfen wir, ob der neue Node im Cluster registriert wurde:

1
kubectl get nodes

Die Ausgabe zeigt nun sowohl den Server-Node als auch den neuen Agent:

1
2
3
NAME        STATUS   ROLES           AGE   VERSION

k3s-server  Ready    control-plane   10m   v1.31.1+k3s2

k3s-agent1  Ready    <none>          45s   v1.31.1+k3s2

Beide Nodes zeigen den Status „Ready“ – der Cluster ist vollständig funktionsfähig und kann Workloads auf beide Nodes verteilen. Standardmäßig plant Kubernetes Workloads auf allen verfügbaren Nodes, einschließlich des Server-Nodes. Um zu verhindern, dass produktive Workloads auf dem Control-Plane-Node laufen, können Sie den Server-Node mit einem Label versehen und die Planung einschränken.

Scheduling für den Control-Plane-Node einschränken

Es gibt zwei Wege, die Workload-Verteilung zu steuern. Der einfachste Weg ist, dem Server-Node ein Taint zu geben, das standardmäßig alle Workloads abweist:

1
kubectl taint nodes k3s-server node-role.kubernetes.io/control-plane=true:NoSchedule

Damit werden bestehende Workloads auf Agent-Nodes migriert und neue Workloads nur noch auf dedizierten Agent-Nodes geplant. Wenn der Server-Node weiterhin als Worker fungieren soll – etwa in kleinen Umgebungen – lassen Sie den Taint weg oder fügen Sie stattdessen ein Label hinzu:

1
2
kubectl label nodes k3s-server node-type=server

kubectl label nodes k3s-agent1 node-type=agent

Mit Labels können Sie spezifische Workloads gezielt auf bestimmte Node-Typen planen – zum Beispiel GPU-intensive KI-Inferenz-Workloads auf Agent-Nodes mit dedizierten Grafikkarten.

Mehrere Agent-Nodes hinzufügen

Um einen dritten Node hinzuzufügen, wiederholen Sie die Installation auf dem neuen Host mit demselben Node-Token. Der Token ändert sich nicht – er ist server-seitig gespeichert und wird für jeden neuen Agent verwendet:

1
curl -sfL https://get.k3s.io | K3S_URL=https://<server-ip>:6443 K3S_TOKEN=<node-token> sh -

Mit drei Nodes wäre der Cluster bereit für produktivere Workloads – Kubernetes verteilt Pods automatisch auf alle verfügbaren Nodes und sorgt für Ausfallsicherheit auf Worker-Ebene.

Installation mit K3D: K3S in Docker-Containern

Nicht immer steht ein dedizierter Server zur Verfügung – etwa auf dem eigenen Laptop oder in einer CI/CD-Umgebung. K3D ist ein Wrapper-Tool, das K3S in Docker-Containern betreibt und so einen vollständigen Multi-Node-Cluster auf einer einzelnen Maschine ermöglicht.

K3D installieren

1
curl -s https://raw.githubusercontent.com/k3d-io/k3d/main/install.sh | bash

Alternativ: K3D über den Paketmanager installieren, z. B.

auf macOS oder auf Ubuntu.

Cluster erstellen

Mit einem einzigen Befehl erstellen Sie einen K3S-Cluster mit einem Server-Node und zwei Agent-Nodes:

1
k3d cluster create mein-cluster --agents 2

K3D erstellt automatisch die Docker-Container für die Nodes und richtet das interne Netzwerk ein. Nach wenigen Sekunden ist der Cluster einsatzbereit.

Die kubeconfig wird automatisch in

geschrieben – kubectl zeigt sofort auf den neuen Cluster:

1
2
3
4
5
6
kubectl get nodes

# Ausgabe:

# NAME               STATUS   ROLES           AGE     VERSION

# k3d-mein-cluster-0  Ready    control-plane   3m12s  v1.31.1+k3s2

# k3d-mein-cluster-1  Ready    <none>          3m8s   v1.31.1+k3s2

# k3d-mein-cluster-2  Ready    <none>          3m4s   v1.31.1+k3s2

K3D eignet sich besonders für lokale Entwicklungsumgebungen und für das Testen von Kubernetes-Konfigurationen, bevor diese in einen produktiven Cluster übertragen werden.

Häufige Probleme und Lösungen

Bei der K3S-Installation können einige Probleme auftreten. Hier sind die häufigsten Fehler und ihre Lösungen:

Problem: Installation hängt bei „Starting k3s“

Das Installationsskript bleibt beim Start des Dienstes hängen. Dies liegt häufig daran, dass der Kubernetes API Server noch auf andere Nodes wartet oder ein Netzwerkproblem vorliegt.

Lösung: Prüfen Sie die Logs des K3S-Dienstes:

1
sudo journalctl -u k3s -f --no-pager

Die Logs zeigen Ihnen, wo der Startprozess blockiert. Typische Ursachen sind fehlerhafte Firewall-Regeln, eine falsche Server-IP oder ein unvollständiger Node-Token.

Problem: Agent-Node wird nicht angezeigt

Der Agent wurde installiert, erscheint aber nicht im Cluster.

Lösung: Prüfen Sie auf dem Agent-Node:

• Ist der k3s-Agent-Dienst gestartet?

  1	sudo systemctl status k3s-agent

• Erreicht der Agent den Server?

  1	curl -k https://<server-ip>:6443

• Sind Firewall-Regeln korrekt? Port 6443 (TCP) und 8472 (UDP) müssen offen sein.

Wenn der Agent den Server nicht erreichen kann, prüfen Sie die Netzwerkkonfiguration. In virtuellen Umgebungen (VirtualBox, Proxmox) ist es häufig erforderlich, die Netzwerkschnittstelle auf „Bridged“ zu setzen, damit die Nodes sich untereinander erreichen können.

Problem: kubectl funktioniert nicht – „Unable to connect to the server“

kubectl kann keine Verbindung zum API Server herstellen.

Lösung: Stellen Sie sicher, dass die kubeconfig-Datei korrekt konfiguriert ist:

1
2
export KUBECONFIG=/etc/rancher/k3s/k3s.yaml

kubectl get nodes

Ist der K3S-Dienst überhaupt gestartet?

1
sudo systemctl status k3s

Wenn der Dienst nicht läuft, starten Sie ihn manuell:

1
2
sudo systemctl start k3s

sudo systemctl enable k3s

Problem: Pods bleiben im Status „Pending“

Deployte Pods starten nicht und bleiben im Status „Pending“.

Lösung: Prüfen Sie, ob ausreichend Ressourcen verfügbar sind. Wenn der Cluster nur über minimale Ressourcen verfügt (512 MB RAM), kann es sein, dass nicht genügend Speicher für die Pod-Scheduling-Entscheidung vorhanden ist. Prüfen Sie mit:

1
kubectl describe pod <pod-name> -n default | grep -A 10 Events

Die Events zeigen Ihnen den konkreten Grund: Ressourcenlimits erreicht, kein passender Node, Volume-Probleme oder Ähnliches.

K3S deinstallieren

Falls Sie K3S wieder entfernen möchten – etwa um eine saubere Neuinstallation durchzuführen – führt der folgende Befehl auf jedem Node zur vollständigen Deinstallation:

1
2
/usr/local/bin/k3s-uninstall.sh        # Für Server-Nodes

/usr/local/bin/k3s-agent-uninstall.sh  # Für Agent-Nodes

Diese Skripte entfernen den systemd-Dienst, das Binärfile und das Datenverzeichnis unter

. Beachten Sie, dass alle Daten im Cluster – Deployments, Services, Volumes – dabei verloren gehen. Sichern Sie bei Bedarf vorher den Cluster-Zustand über etcd-Snapshots.

Empfohlene nächste Schritte nach der Installation

Der Cluster ist installiert und funktioniert. Doch ein frisch installiertes K3S ist erst der Anfang. Die folgenden Schritte helfen Ihnen, den Cluster in einen produktionsreifen Zustand zu überführen:

• Helm installieren: Mit Helm können Sie komplexe Anwendungen mit einem einzigen Befehl deployen.

  1	curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash

• Longhorn für Persistent Storage: Der Local Path Provisioner von K3S ist für einfache Szenarien ausreichend. Für produktive Storage-Lösungen mit Replikation empfiehlt sich Longhorn – besonders für Datenbanken und StatefulSets.
• Monitoring einrichten: Prometheus und Grafana über Helm deployen, um Metriken und Visualisierungen zu erhalten.
• Cluster-Backup: Regelmäßige etcd-Snapshots konfigurieren, um im Notfall den Cluster-Zustand wiederherstellen zu können.
• Zertifikatsrotation: TLS-Zertifikate von K3S haben eine Gültigkeit von 12 Monaten. Richten Sie eine automatische Erneuerung ein, um Zertifikatsabläufe zu vermeiden.

Wer sich für den Betrieb von KI-Workloads auf K3S interessiert, findet in Ollama und vLLM zwei bewährte Optionen für das Selbsthosting von Large Language Models. K3S eignet sich hervorragend als Orchestrierungsschicht für GPU-basierte Inferenz-Workloads.

Sie möchten K3S oder Kubernetes produktiv einsetzen?

Wir unterstützen Sie bei der Planung, Installation und Absicherung Ihrer Kubernetes-Umgebung – ob mit K3S für Edge-Standorte oder einem vollständigen Kubernetes-Cluster für produktive Workloads. Kontaktieren Sie uns über unser Kontaktformular – wir melden uns innerhalb von 24 Stunden bei Ihnen.