k3s: Leichtgewichtiges Kubernetes für den eigenen Server einrichten

Wer seine containerisierten Anwendungen bisher mit Docker Compose verwaltet, stößt an Grenzen: kein Neustart-Management über Nodes hinweg, kein eingebauter Load Balancer, keine standardisierte Rollenverteilung. Ein vollständiger Kubernetes-Cluster ist dagegen aufwendig zu installieren. k3s schließt diese Lücke: Die zertifizierte, leichtgewichtige Kubernetes-Distribution von Rancher/SUSE (heute ein CNCF-Projekt) passt in ein einziges Binary unter 70 MB, ist in unter einer Minute installiert und bringt alle wesentlichen Komponenten bereits mit. Diese Anleitung zeigt, wie Sie k3s auf einem einzelnen Linux-Server einrichten, ein erstes Deployment über den vorinstallierten Traefik-Ingress erreichbar machen und Portainer als Oberfläche anbinden.

Voraussetzungen

1. Betriebssystem: Linux-Server oder VM – Ubuntu 22.04/24.04, Debian 11/12, RHEL/CentOS oder SUSE; Kernel 5.x empfohlen
2. Hardware (Server-Node): Mindestens 2 CPU-Kerne und 2 GB RAM (x86_64, arm64 oder armhf); SSD empfohlen, besonders auf ARM-Hardware. Mit eigenen Anwendungen und Portainer planen Sie 4 GB RAM ein.
3. Hardware (Agent-Node, optional): Mindestens 1 CPU-Kern und 512 MB RAM
4. Speicherplatz: Mindestens 10 GB frei
5. Zugriff: Root- oder sudo-Zugriff auf den Server
6. Netzwerk: Internetverbindung für den initialen Download (~70 MB); TCP 80 und 443 für den Ingress; TCP 6443 nur für Ihre Admin-Rechner und weitere Nodes; bei Multi-Node UDP 8472 nur zwischen den Nodes (nie ins Internet öffnen)
7. Hostname: Eindeutiger Hostname pro Node – bei VM-Klonen unbedingt vorher prüfen
8. Vorkenntnisse: Docker-Compose-Erfahrung hilfreich; grundlegende Linux-Kenntnisse (SSH, sudo, Texteditor) erforderlich

k3s im Überblick: Was Sie bekommen

Die Tabelle zeigt den Unterschied zwischen k3s und einem vollständigen Kubernetes-Cluster.

k3s ist vollständig API-konform: Standard-Manifeste, kubectl und Helm funktionieren ohne Anpassungen. k3s lässt Alphafeatures und cloudspezifische Treiber weg, die auf Bare Metal keine Rolle spielen.

Schritt 1: k3s installieren

Führen Sie den folgenden Befehl als root oder mit sudo auf dem Server aus:

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

Das Skript lädt das k3s-Binary herunter, richtet einen systemd-Service ein und startet den Cluster sofort. Die Installation dauert meist unter einer Minute.

Prüfen Sie danach den Status des Dienstes und ob der Node bereit ist:

sudo systemctl status k3s
sudo kubectl get nodes
sudo kubectl get pods -A

Verifizieren: sudo kubectl get nodes zeigt Ihren Server mit Status Ready. sudo kubectl get pods -A listet unter anderem Pods für traefik, coredns und metrics-server im Namespace kube-system auf – alle im Status Running.

Schritt 2: kubeconfig für normale Benutzer einrichten

Die kubeconfig liegt standardmäßig unter /etc/rancher/k3s/k3s.yaml und ist nur für root lesbar. Um kubectl als normaler Benutzer zu verwenden, kopieren Sie die Datei in Ihr Home-Verzeichnis:

mkdir -p ~/.kube
sudo cp /etc/rancher/k3s/k3s.yaml ~/.kube/config
sudo chown $(id -u):$(id -g) ~/.kube/config
export KUBECONFIG=~/.kube/config

Damit die Umgebungsvariable dauerhaft gilt, tragen Sie sie in Ihre ~/.bashrc oder ~/.profile ein:

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

Alternativ können Sie in der k3s-Konfigurationsdatei write-kubeconfig-mode: "0644" setzen – dann ist /etc/rancher/k3s/k3s.yaml direkt für alle Benutzer lesbar (nur sinnvoll auf Systemen mit kontrolliertem Benutzerzugriff).

Verifizieren: kubectl get nodes (ohne sudo) gibt dieselbe Ausgabe wie zuvor – der Node ist Ready.

Schritt 3: Optionale Konfigurationsdatei anlegen

Für typische Anpassungen – etwa das Hinterlegen einer externen IP oder Domain für das TLS-Zertifikat des API-Servers – verwenden Sie die Konfigurationsdatei /etc/rancher/k3s/config.yaml. Diese Datei muss vor der Installation vorhanden sein oder k3s muss danach neu gestartet werden.

sudo mkdir -p /etc/rancher/k3s
sudo tee /etc/rancher/k3s/config.yaml <<'EOF'
tls-san:
  - "IHRE-EXTERNE-IP-ODER-DOMAIN"
write-kubeconfig-mode: "0644"
EOF

Nach einer Änderung an config.yaml starten Sie k3s neu:

sudo systemctl restart k3s

ServiceLB (den eingebauten Load Balancer) oder andere Komponenten deaktivieren Sie ebenfalls hier, etwa wenn Sie MetalLB oder einen externen Load Balancer einsetzen:

# /etc/rancher/k3s/config.yaml
tls-san:
  - "192.168.1.100"
  - "k3s.example.com"
write-kubeconfig-mode: "0644"
disable:
  - servicelb

Verifizieren: sudo systemctl status k3s zeigt active (running), kubectl get nodes meldet weiter Ready. Mit disable: servicelb taucht in kubectl get pods -A kein svclb--Pod mehr auf.

Schritt 4: Erstes Deployment mit Traefik-Ingress

k3s bringt Traefik v3 als Ingress-Controller vorinstalliert mit. Sie erstellen jetzt ein Test-Deployment mit dem traefik/whoami-Image, das auf HTTP-Anfragen mit Informationen zur Anfrage antwortet. Legen Sie eine Datei whoami-demo.yaml an:

---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: whoami
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      app: whoami
  template:
    metadata:
      labels:
        app: whoami
    spec:
      containers:
      - name: whoami
        image: traefik/whoami:latest
        ports:
        - containerPort: 80
        resources:
          requests:
            cpu: "50m"
            memory: "32Mi"
          limits:
            cpu: "200m"
            memory: "64Mi"
---
apiVersion: v1
kind: Service
metadata:
  name: whoami
  namespace: default
spec:
  selector:
    app: whoami
  ports:
  - port: 80
    targetPort: 80
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: whoami
  namespace: default
  annotations:
    traefik.ingress.kubernetes.io/router.entrypoints: web
spec:
  rules:
  - host: whoami.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: whoami
            port:
              number: 80

Ersetzen Sie whoami.example.com durch eine Domain oder einen Hostnamen, der auf die IP Ihres Servers zeigt. Für ein produktives Deployment legen Sie statt latest einen festen Image-Tag fest. Wenden Sie das Manifest an:

kubectl apply -f whoami-demo.yaml

Verifizieren: Nach kurzer Zeit (der Image-Pull kann eine Minute dauern) zeigt kubectl get pods den whoami-Pod im Status Running. Ein curl -H "Host: whoami.example.com" http://<SERVER-IP>/ liefert eine Textantwort mit Request-Headern und Hostname zurück.

Schritt 5: Traefik anpassen

Ein häufiger Stolperstein: Die Datei /var/lib/rancher/k3s/server/manifests/traefik.yaml wird bei jedem k3s-Start automatisch überschrieben. Direktes Editieren dieser Datei hat deshalb keinen dauerhaften Effekt. Anpassungen nehmen Sie stattdessen über eine HelmChartConfig-Ressource vor, die k3s im selben Auto-Deploy-Verzeichnis erkennt:

sudo tee /var/lib/rancher/k3s/server/manifests/traefik-config.yaml <<'EOF'
apiVersion: helm.cattle.io/v1
kind: HelmChartConfig
metadata:
  name: traefik
  namespace: kube-system
spec:
  valuesContent: |-
    dashboard:
      enabled: true
    logs:
      general:
        level: INFO
EOF

k3s erkennt diese Datei automatisch und wendet die Helm-Values auf die Traefik-Installation an. Für einen anderen Ingress-Controller wie Nginx oder Caddy deaktivieren Sie Traefik über disable: [traefik] in config.yaml.

Verifizieren: kubectl -n kube-system get helmchartconfig traefik listet die Ressource, und kubectl -n kube-system get pods zeigt einen neu gestarteten traefik-Pod im Status Running.

Schritt 6: Portainer als Management-Oberfläche anbinden

Portainer aus der Docker-Welt verwaltet auch den k3s-Cluster. Es gibt zwei Wege:

Weg A: Portainer Agent per kubectl deployen (empfohlen)

Wenden Sie das offizielle Portainer-Agent-Manifest auf Ihrem Cluster an. Die Version im Pfad (ce2-45) muss zur Version Ihres Portainer-Servers passen; Portainer zeigt den passenden Befehl im Assistenten an:

kubectl apply -f https://downloads.portainer.io/ce2-45/portainer-agent-k8s-nodeport.yaml

Der Agent läuft als DaemonSet und ist über NodePort 30778 erreichbar. In Ihrer Portainer-Instanz wählen Sie Environments > Add Environment > Kubernetes > Agent und tragen <SERVER-IP>:30778 als Endpoint ein. Geben Sie Port 30778 in der Firewall nur für den Portainer-Server frei.

Weg B: kubeconfig importieren

Alternativ laden Sie die Datei /etc/rancher/k3s/k3s.yaml in Portainer unter Environments > Add > Kubernetes > Import from kubeconfig hoch. Achten Sie darauf, dass die IP-Adresse im server-Feld der kubeconfig von außen erreichbar ist – standardmäßig steht dort 127.0.0.1, das Sie durch die tatsächliche Server-IP ersetzen.

Verifizieren: In Portainer erscheint der k3s-Cluster unter Environments mit Status „Up“ und zeigt die Anzahl der laufenden Pods und Nodes an.

Schritt 7 (optional): Agent-Node hinzufügen

k3s skaliert bei Bedarf auf mehrere Nodes. Um einen weiteren Linux-Server als Worker (Agent-Node) hinzuzufügen, benötigen Sie den Node-Token vom Server:

# Auf dem Server-Node ausführen:
sudo cat /var/lib/rancher/k3s/server/node-token

Auf dem Agent-Node führen Sie dann aus (Platzhalter durch tatsächliche Werte ersetzen):

curl -sfL https://get.k3s.io | K3S_URL=https://<SERVER-IP>:6443 K3S_TOKEN=<NODE_TOKEN> sh -

Hinweis zur Firewall: TCP-Port 6443 muss vom Agent-Node zum Server erreichbar sein. Bei Multi-Node-Betrieb mit Flannel-VXLAN zusätzlich UDP-Port 8472 zwischen den Nodes freigeben, nie ins Internet.

Verifizieren: kubectl get nodes auf dem Server zeigt beide Nodes mit Status Ready.

Firewall-Ports im Überblick

Troubleshooting / Typische Fehler

kubectl schlägt mit „permission denied“ fehl

/etc/rancher/k3s/k3s.yaml ist standardmäßig nur für root lesbar. Lösung: kubeconfig in das Home-Verzeichnis kopieren und Eigentümer anpassen (siehe Schritt 2) oder write-kubeconfig-mode: "0644" in config.yaml setzen.

Agent-Node kann sich nicht verbinden

Häufigste Ursache: Port 6443 ist durch UFW oder firewalld blockiert. Prüfen und öffnen Sie den Port:

# UFW
sudo ufw allow 6443/tcp
# firewalld
sudo firewall-cmd --add-port=6443/tcp --permanent && sudo firewall-cmd --reload

Traefik-Anpassungen werden nicht übernommen

Die Datei traefik.yaml im Auto-Deploy-Verzeichnis wird bei jedem Start überschrieben. Immer eine separate HelmChartConfig-Datei (z. B. traefik-config.yaml) verwenden – niemals traefik.yaml direkt editieren.

Nodes haben denselben Namen / Konflikte bei VM-Klonen

Jeder Node benötigt einen eindeutigen Hostnamen. Bei geklonten VMs: Hostname vor der k3s-Installation ändern (hostnamectl set-hostname NEUER-NAME) oder die Umgebungsvariable K3S_NODE_NAME beim Installationsaufruf setzen.

k3s startet auf Raspberry Pi nicht korrekt

Auf Raspberry Pi OS müssen cgroups in /boot/firmware/cmdline.txt aktiviert sein (Debian 11 und ältere Pi-OS-Versionen: /boot/cmdline.txt). Fügen Sie folgende Parameter an das Ende der bestehenden Zeile an (kein Zeilenumbruch):

cgroup_memory=1 cgroup_enable=memory

Danach Neustart und erneut installieren.

ServiceLB kollidiert mit MetalLB oder Cloud-LoadBalancer

Wer MetalLB oder einen externen Load Balancer betreibt, muss ServiceLB deaktivieren. In /etc/rancher/k3s/config.yaml:

disable:
  - servicelb

SQLite im HA-Betrieb verwenden

SQLite ist ausschließlich für Single-Node-Deployments geeignet. Für Hochverfügbarkeit (mindestens 3 Server-Nodes) muss beim ersten Server-Node das Flag --cluster-init gesetzt werden; alle weiteren Server-Nodes verbinden sich dann über etcd. Eine bestehende Single-Node-Installation mit SQLite wandeln Sie um, indem Sie den k3s-Server einmal mit --cluster-init neu starten (z. B. cluster-init: true in config.yaml).

Häufige Fragen

Brauche ich Docker, um k3s zu betreiben?

Nein. k3s verwendet standardmäßig containerd als Container-Runtime – Docker ist weder erforderlich noch installiert. Docker-Unterstützung lässt sich über das --docker-Flag aktivieren, ist aber nicht empfohlen.

Kann ich meine Docker-Compose-Dateien direkt in k3s nutzen?

Nicht direkt. Kubernetes verwendet eigene Manifest-Formate (Deployment, Service, Ingress). Das Tool Kompose (kompose.io) kann docker-compose.yml-Dateien in Kubernetes-Manifeste umwandeln.

Was ist der Unterschied zwischen k3s, k3d und minikube?

k3d führt k3s in Docker-Containern aus, minikube ist ebenfalls ein lokales Entwicklungswerkzeug; beide dienen Entwicklung und CI. k3s ist eine produktionstaugliche Distribution für Linux-Server (Bare Metal oder VM).

Wie aktualisiere ich k3s?

Das Installationsskript kann erneut mit einer Zielversion ausgeführt werden:

curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION=v1.37.0+k3s1 sh -

Für automatische Updates in Clustern empfiehlt Rancher den System Upgrade Controller.

Ist k3s für den produktiven Betrieb geeignet?

Ja. k3s ist CNCF-zertifiziert und wird aktiv weiterentwickelt. Die SQLite-Datenbank eignet sich nur für Single-Node; für produktive Multi-Node-Szenarien wird HA mit eingebettetem etcd (mindestens 3 Server-Nodes) empfohlen.

Was passiert mit meinen Daten bei einem Node-Ausfall?

Der eingebaute Local-Path-Provisioner speichert PersistentVolumes unter /var/lib/rancher/k3s/storage lokal auf dem Node. Bei einem Node-Ausfall sind diese Daten nicht automatisch verfügbar. Für produktive Daten empfiehlt sich ein verteilter Speicher wie Longhorn oder NFS.

Fazit

k3s führt ohne externe Abhängigkeiten von Docker Compose zu Kubernetes und bleibt voll API-kompatibel. Ein einzelner Linux-Server oder eine kleine VM-Gruppe wird zum vollwertigen Cluster, den Sie mit denselben Tools und Manifesten bedienen wie jeden anderen. Traefik v3 und ServiceLB decken die gängigen Anwendungsfälle ohne zusätzliche Komponenten ab. Der Trade-off: Sie lernen Kubernetes-Konzepte (Deployments, Services, Ingress, PersistentVolumeClaims), was sich lohnt, sobald Sie mehrere Dienste verwalten oder Hochverfügbarkeit brauchen.

Weiterführende Anleitungen und Quellen

1. Docker Compose: Multi-Container-Stacks aufbauen – die Grundlage vor k3s
2. Traefik als Docker-Reverse-Proxy mit automatischem HTTPS – Traefik-Konzepte, die auch in k3s gelten
3. Portainer installieren: Schritt-für-Schritt-Anleitung – Portainer als Management-Oberfläche einrichten
4. Docker-Images auf Schwachstellen scannen mit Trivy – Container-Sicherheit für den k3s-Cluster
5. k3s Quick-Start Guide (offizielle Dokumentation)
6. k3s Systemanforderungen (offizielle Dokumentation)
7. Portainer Agent auf Kubernetes installieren (offizielle Dokumentation)