K3s-Cluster aufsetzen
Schritt-für-Schritt-Anleitung zur Installation eines K3s-Clusters mit Fokus auf Control Plane, VPN, Netzwerkinterfaces und YAML-Konfiguration – ideal für Bare-Metal- oder Homelab-Umgebungen.
Wie man einen K3s-Cluster aufzieht
Aufbauend auf unseren vorherigen Artikel Wie man Rancher Server und K3s auf Bare Metal installiert wollen wir unser Cluster nun um mehrere Worker-Nodes erweitern.
Vorwort zur VPN-Nutzung und Netzwerkanforderungen
In unserem Setup sind die Maschinen leider nur über ein VPN-Netz verbunden. Das hat keine Sicherheitsgründe, sondern ist notwendig, wenn man die Maschinen nicht am selben Ort betreiben kann. Im besten Fall läuft Kubernetes on-prem in einem Rechenzentrum, und die Netzwerkgeschwindigkeit spielt eine tragende Rolle. Daher sind größere Setups wie K8s, RKE2, Charmed Kubernetes nicht für ein Homelab geeignet. Es gibt häufig Probleme mit dem darunterliegenden VPN in Bezug auf die CNI-Implementierungen wie Calico, Cilium etc. Diese greifen in die Netzwerk-Interfaces ein, genauso wie z. B. WireGuard oder OpenVPN. Dabei kann es zu Problemen kommen und erfordert erhöhten Konfigurationsaufwand. Außerdem setzen große Kubernetes-Distributionen ein starkes, verlässliches Netzwerk voraus, was VPN unter Umständen nicht bieten kann.
Maschinen-Setup
Um ein realistisches Cluster zu erzeugen, benutzen wir folgende Maschinen:
- 4 × 32 GB RAM, AMD Ryzen 7, 512 GB SSD
Diese sind über ein VPN-Netz verbunden und alle haben Ubuntu Server 22.04.5 installiert.
K3s als beste Option
Die von SUSE entwickelte K3s-Distribution bietet für solche Probleme eine Lösung. Ein Kubernetes-Cluster auf Edge-Devices aufzuziehen, wo Netzwerkschwankungen dazugehören. Ein typischer Anwendungsfall ist IoT. Es eignet sich daher bestens, es auf einem Homelab zu installieren, auch mit VPN.
K3s Control Plane
Um einen Kubernetes-Cluster mit K3s aufzubauen, beginnt man mit dem Einrichten der Control Plane – also dem ersten Server-Node, der später auch Agent-Nodes verwaltet. Die Konfiguration dieses Knotens ist entscheidend für Netzwerkverhalten, Sicherheit und Erweiterbarkeit des Clusters.
Bevor du K3s installierst, solltest du dir Gedanken über grundlegende Einstellungen machen – insbesondere dann, wenn du ein reproduzierbares oder sicheres Setup planst (z. B. mit mehreren Nodes, eigener Netzwerktopologie oder ohne Standardkomponenten wie Traefik).
1. Konfigurationsdatei vorbereiten
Die Installation von K3s lässt sich gezielt über eine YAML-Konfigurationsdatei steuern. Diese Datei sollte vor der Installation unter folgendem Pfad angelegt werden:
1
/etc/rancher/k3s/config.yaml
Beispielkonfiguration:
1
2
3
4
5
6
7
8
9
cluster-init: true
node-ip: 192.168.1.10
advertise-address: 192.168.1.10
flannel-iface: eth0
token: mein-sicheres-token
secrets-encryption: true
tls-san:
- "k3s.example.local"
- "192.168.1.10"
Diese Datei legt fest:
- dass der Node einen neuen Cluster startet (
cluster-init: true), - welche IPs verwendet werden,
- welche Komponenten deaktiviert werden,
- welche TLS-Zugänge erlaubt sind,
- ob Daten verschlüsselt gespeichert werden sollen.
2. Cluster-Initialisierung und Sicherheit
Damit K3s einen neuen Cluster initialisiert, muss auf dem ersten Server-Node der Parameter cluster-init: true gesetzt
werden. Dieser Node übernimmt die Rolle der Control Plane und speichert den initialen Zustand des Clusters. Weitere
Server-Nodes (z. B. in einem High-Availability-Setup) oder Agent-Nodes verbinden sich anschließend mit diesem Knoten.
Weitere sicherheitsrelevante Optionen:
token: Ein gemeinsam genutztes Secret zur Authentifizierung von Agent- oder weiteren Server-Nodes.secrets-encryption: Aktiviert die Verschlüsselung sensibler Kubernetes-Daten wie Secrets auf dem Dateisystem – empfohlen für produktive Setups.tls-san: Zusätzliche IPs oder DNS-Namen, unter denen der API-Server erreichbar ist. Notwendig bei Zugriff über Hostnamen oder Load-Balancer.
3. Netzwerk- und Node-Konfiguration
Eine saubere Netzwerkkonfiguration ist besonders wichtig, wenn dein Server mehrere Interfaces besitzt (z. B. LAN + VPN) oder du in einer virtuellen Umgebung arbeitest. Du kannst damit vermeiden, dass K3s automatisch die falsche Schnittstelle auswählt.
Wichtige Parameter:
node-ip: Die IP-Adresse, mit der der Node im Cluster kommuniziert.advertise-address: Die IP-Adresse, unter der der API-Server für andere Nodes erreichbar ist.flannel-iface: Die Netzwerkschnittstelle, die für das Pod-Netzwerk verwendet werden soll.
4. Installation starten
Sobald die Konfigurationsdatei vollständig erstellt und gespeichert wurde, kannst du die Installation starten. Das
offizielle K3s-Installationsskript erkennt die config.yaml automatisch und übernimmt alle dort definierten
Einstellungen.
Führe auf dem Server folgenden Befehl aus:
1
curl -sfL https://get.k3s.io | sh -
Der Dienst wird nach der Installation automatisch gestartet. Allerdings funktioniert der Befehl kubectl nicht sofort
ohne Weiteres, weil die Konfigurationsdatei, die kubectl benötigt, nicht im Standardpfad (~/.kube/config) liegt.
K3s legt die kubeconfig standardmäßig unter folgendem Pfad ab:
1
/etc/rancher/k3s/k3s.yaml
5. Zugriff auf den Cluster von deiner lokalen Maschine
Um von deiner lokalen Maschine aus auf den K3s-Cluster zuzugreifen, musst du die kubeconfig-Datei vom Server kopieren
und entsprechend anpassen.
Schritt 1: Datei kopieren
Kopiere die kubeconfig-Datei vom Server auf deine lokale Maschine:
1
scp user@<server-ip>:/etc/rancher/k3s/k3s.yaml ~/.kube/config
Ersetze <server-ip> durch die IP-Adresse deines K3s-Servers und user durch deinen Benutzernamen.
Schritt 2: Server-Adresse anpassen
Öffne die kopierte Datei ~/.kube/config in einem Texteditor und ersetze die Zeile:
1
server: https://127.0.0.1:6443
durch:
1
server: https://<server-ip>:6443
Ersetze <server-ip> durch die öffentliche IP-Adresse oder den DNS-Namen deines K3s-Servers.
Schritt 3: Dateiberechtigungen setzen
Setze die richtigen Berechtigungen für die kubeconfig-Datei:
1
chmod 600 ~/.kube/config
Schritt 4: Umgebungsvariable setzen (optional)
Um kubectl dauerhaft mit der richtigen Konfigurationsdatei arbeiten zu lassen, kannst du die Umgebungsvariable
KUBECONFIG setzen. Füge folgende Zeile zu deiner ~/.bashrc oder ~/.zshrc hinzu:
1
export KUBECONFIG=$HOME/.kube/config
Lade die Konfiguration neu:
1
source ~/.bashrc
Schritt 5: Verbindung testen
Teste die Verbindung zum Cluster:
1
kubectl get nodes
Wenn alles korrekt eingerichtet ist, wird der erste Node mit Status Ready angezeigt – und ist bereit für weitere
Agent-Nodes oder Control-Plane-Knoten.
1
2
3
kubectl get nodes
NAME STATUS ROLES AGE VERSION
k3s-control-plane Ready control-plane,etcd,master 1h v1.32.4+k3s1
Fazit
Der K3s-Server ist eingerichtet und bereit. Im nächsten Artikel zeigen wir, wie Agent-Nodes dem Cluster beitreten können.
Bildnachweis
Image by Pete Linforth from Pixabay
Dieser Beitrag wurde erstellt von OSAIA Consulting – Experten für Platform Engineering, Automatisierung und Softwarearchitektur.
💬 Fragen oder Feedback?
Wir freuen uns über den Austausch – schreibt uns jederzeit über unsere Website.