b0000 - k3s-Referenz
Quelle: pkr-lab/pkr-lab-docs/capulus/capulus-core/b-kubernetes-gitops/b0000-k3s.md
k3s-Referenz
Dieses Dokument behandelt k3s-Konfiguration, häufige Operationen und Wartung.
Cluster-Topologie
Es gibt drei getrennte k3s-Cluster (Überblick: a0010):
| Cluster | k3s-Server | Agents | Pod-/Service-CIDR | Playbook |
|---|---|---|---|---|
| TECH | homeserver (.94, bare metal) |
worker-0, worker-1 |
10.42.0.0/16 / 10.43.0.0/16 |
make install, make controlplane-1, make worker-1 |
| PROD | prod-vm (.99, KVM-VM auf dem homeserver) |
— | 10.46.0.0/16 / 10.47.0.0/16 |
make prod |
| ENTW | entw-vm (.100, KVM-VM auf worker-1) |
— | 10.44.0.0/16 / 10.45.0.0/16 |
make entw |
Alle drei nutzen dieselbe k3s-Rolle. Die Unterschiede stehen in den host_vars (host_vars/prod-vm/,
host_vars/entw-vm/): eigene CIDRs, und ENTW schaltet Audit-Log und Secrets-Encryption ab
(Wegwerf-Cluster). Der Rest dieses Dokuments beschreibt, sofern nicht anders gesagt, den
TECH-Cluster. In den VMs läuft k3s nur als Server (Control-Plane + Worker in einem), kubectl dort
per sudo k3s kubectl ….
TECH-Cluster: drei Nodes
Im Ansible-Inventar heißen die Nodes controlplane-0 (k3s-Nodename homeserver), controlplane-1 (k3s-Nodename worker-0) und worker-1. Die Tabelle nennt die k3s-Nodenamen, siehe 400a0.
Der TECH-Cluster besteht aus drei Nodes:
| Node | IP | Rolle | Ansible-Gruppe |
|---|---|---|---|
| homeserver | 192.168.178.94 | Control-Plane + Worker (k3s server) |
k3s_servers, k3s_primary |
| worker-0 | 192.168.178.95 | Worker (k3s agent) |
k3s_servers (Inventar-Host controlplane-1) |
| worker-1 | 192.168.178.96 | Worker (k3s agent) |
k3s_agents |
Nach der Umstellung auf zwei Control-Planes (Runbook in 400a0): Der Node
worker-0heißtcontrolplane-1, ist k3s-Server mit embedded etcd (zusammen mithomeserver) und läuft dauerhaft. Bis zum Wartungsfenster gilt die Tabelle oben.
worker-0 und worker-1 sind identisch aufgebaute, reine k3s-Compute-Nodes
(kein Docker-Compose-Dienst läuft mehr fest verdrahtet auf einem bestimmten
Host). Der Kubernetes-Scheduler verteilt Pods frei auf alle drei Nodes.
Persistenter Storage liegt zentral auf dem UGREEN NAS (nas-StorageClass,
NFS) — jeder Node kann mounten, siehe capulus-core/2-betrieb-hardware/20000-nas-storage.md.
Cluster-Provisionierung
# Schritt 1: Control-Plane + alle Dienste auf homeserver
make install
# Schritt 2: worker-0 als Worker-Node beitreten lassen
make controlplane-1
# Schritt 3: worker-1 als Worker-Node beitreten lassen
make worker-1
# Nur den k3s-Agent auf worker-0 neu deployen (z.B. nach Token-Rotation)
make k3s-agent
Bekannter Flake: "D-Bus connection terminated while waiting for jobs" —
get-k3s.sh ruft intern systemctl enable --now auf; ist dbus-daemon zu
diesem Zeitpunkt mit paralleler apt/snapd/PackageKit-Aktivität beschäftigt,
bricht die D-Bus-Verbindung ab und der Installer-Task schlägt mit rc=1 fehl,
obwohl der Service danach meist trotzdem sauber hochkommt. Die Install-Tasks
in roles/k3s/tasks/main.yml und roles/k3s_agent/tasks/main.yml
wiederholen den (idempotenten) Installer deshalb bis zu 3× mit 10s Abstand.
Bricht der Task trotzdem endgültig ab: make controlplane-1 (bzw. make install)
einfach erneut laufen lassen.
Node-Status prüfen
kubectl get nodes -o wide
# Erwartet:
# NAME STATUS ROLES AGE VERSION INTERNAL-IP
# homeserver Ready control-plane Xm v1.36.x+k3s1 192.168.178.94
# (nach der etcd-Umstellung: control-plane,etcd; kein master-Label mehr)
# worker-0 Ready <none> Xm v1.36.x+k3s1 192.168.178.95
# worker-1 Ready <none> Xm v1.36.x+k3s1 192.168.178.96
Worker-Node verwalten
# Node cordon (kein neuer Workload wird geplant)
kubectl cordon worker-0
# Node drain (alle Pods evakuieren, z.B. vor Wartung)
kubectl drain worker-0 --ignore-daemonsets --delete-emptydir-data
# Node wieder in Betrieb nehmen
kubectl uncordon worker-0
# Labels anzeigen
kubectl get node worker-0 --show-labels
# Node-Label setzen (z.B. für NodeSelector in Pods)
kubectl label node worker-0 node-role.kubernetes.io/worker=worker
Worker-Node entfernen (permanent)
# 1. Node im Cluster löschen
kubectl delete node worker-0
# 2. k3s-agent auf worker-0 deinstallieren (via SSH)
ssh [email protected] 'sudo /usr/local/bin/k3s-agent-uninstall.sh'
Konfigurationsdatei
Die k3s-Server-Konfiguration liegt auf dem Server unter /etc/rancher/k3s/config.yaml.
Pfad: /etc/rancher/k3s/config.yaml
# k3s server configuration
write-kubeconfig-mode: "0644"
tls-san:
- "192.168.1.100" # Server-LAN-IP
- "homeserver" # Hostname
- "127.0.0.1" # Loopback
cluster-cidr: "10.42.0.0/16" # Pod-Netz-CIDR
service-cidr: "10.43.0.0/16" # Service-Netz-CIDR
node-name: "homeserver"
Nach Änderung k3s neu starten:
sudo systemctl restart k3s
Service-Unit: /etc/systemd/system/k3s.service
Datenverzeichnis: /var/lib/rancher/k3s/
Kubeconfig: /etc/rancher/k3s/k3s.yaml (root) und /home/ubuntu/.kube/config (ubuntu)
kubectl-Cheatsheet
Cluster-Status
# Node-Status
kubectl get nodes
kubectl get nodes -o wide # mit IPs und OS-Info
# Alle Pods aus allen Namespaces
kubectl get pods -A
kubectl get pods -A -o wide # mit Node und IP
# Alle Resources in einem Namespace
kubectl get all -n argocd
# Cluster-Info
kubectl cluster-info
# Verfügbare API-Resources
kubectl api-resources
Workload-Operationen
# Resource beschreiben (Events, Config)
kubectl describe pod <pod-name> -n <namespace>
kubectl describe node homeserver
# Logs
kubectl logs <pod-name> -n <namespace>
kubectl logs <pod-name> -n <namespace> --previous # vorher abgestürzter Container
kubectl logs <pod-name> -n <namespace> -f # follow
kubectl logs <pod-name> -n <namespace> -c <container> # spezifischer Container
# Kommando im Pod ausführen
kubectl exec -it <pod-name> -n <namespace> -- /bin/sh
# Port-Forward
kubectl port-forward svc/<service-name> 8080:80 -n <namespace>
kubectl port-forward pod/<pod-name> 8080:80 -n <namespace>
# Deployment skalieren
kubectl scale deployment <name> --replicas=2 -n <namespace>
# Deployment neu starten (Rolling-Restart)
kubectl rollout restart deployment/<name> -n <namespace>
# Rollout-Status
kubectl rollout status deployment/<name> -n <namespace>
# Rollout-Historie
kubectl rollout history deployment/<name> -n <namespace>
# Rollback
kubectl rollout undo deployment/<name> -n <namespace>
Resource-Inspektion
# YAML einer Resource
kubectl get deployment <name> -n <namespace> -o yaml
# Secret-Wert (base64-decoded)
kubectl get secret <name> -n <namespace> -o jsonpath='{.data.<key>}' | base64 -d
# Top Nodes und Pods (braucht metrics-server)
kubectl top nodes
kubectl top pods -A
kubectl top pods -A --sort-by=cpu
kubectl top pods -A --sort-by=memory
# Events (letzte Stunde)
kubectl get events -A --sort-by='.lastTimestamp'
kubectl get events -n <namespace> --sort-by='.lastTimestamp'
Namespace-Operationen
# Namespaces auflisten
kubectl get namespaces
# Namespace erstellen
kubectl create namespace my-app
# Namespace löschen (löscht alle Resources darin!)
kubectl delete namespace my-app
# Default-Namespace für aktuellen Context setzen
kubectl config set-context --current --namespace=argocd
Apply & Delete
# Manifest applyen
kubectl apply -f manifest.yaml
kubectl apply -f directory/ # alle YAMLs im Verzeichnis
# Resource löschen
kubectl delete -f manifest.yaml
kubectl delete pod <name> -n <namespace>
kubectl delete pod <name> -n <namespace> --force --grace-period=0 # Force-Kill
# Dry-Run (Vorschau)
kubectl apply -f manifest.yaml --dry-run=client
kubectl apply -f manifest.yaml --dry-run=server
Storage — local-path-Provisioner
k3s liefert die local-path-StorageClass standardmäßig mit. Sie provisioniert
PersistentVolumes über Host-Path-Verzeichnisse auf der NVMe-SSD.
# StorageClass prüfen
kubectl get storageclass
# Erwartet:
# NAME PROVISIONER RECLAIMPOLICY VOLUMEBINDINGMODE
# local-path (default) rancher.io/local-path Delete WaitForFirstConsumer
Daten-Speicherort auf dem Host: /var/lib/rancher/k3s/storage/
Beispiel-PVC:
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: my-data
namespace: my-app
spec:
accessModes:
- ReadWriteOnce
storageClassName: local-path
resources:
requests:
storage: 10Gi
Wichtige Limitierungen im Multi-Node-Cluster:
- Nur
ReadWriteOnce— nicht parallel von mehreren Pods mountbar. - Daten leben auf dem Node, auf dem der Pod scheduled wurde — nicht repliziert.
Ein Pod mit einemlocal-path-PVC läuft immer auf demselben Node. Delete-Reclaim-Policy — beim Löschen der PVC werden die PV-Daten ebenfalls gelöscht.WaitForFirstConsumer— PV wird erst angelegt, wenn ein Pod gescheduled wird.- Für Workloads die auf einem bestimmten Node laufen müssen (wegen PVC-Affinität),
nodeSelectorodernodeNameim Pod/Deployment setzen.
Für größere/geteilte Datenmengen gibt es zusätzlich die NFS-backed
nas-StorageClass (UGREEN NAS) — kein WaitForFirstConsumer/Node-Pin
nötig, jeder Node kann mounten. Details: capulus-core/2-betrieb-hardware/20000-nas-storage.md.
Networking — Flannel VXLAN
k3s nutzt Flannel im VXLAN-Mode für Pod-zu-Pod-Networking.
# Flannel-Pods
kubectl get pods -n kube-system -l app=flannel
# CNI-Konfiguration
cat /var/lib/rancher/k3s/agent/etc/cni/net.d/10-flannel.conflist
# Pod-Netz-CIDR
kubectl get nodes -o jsonpath='{.items[*].spec.podCIDR}'
Netzbereiche:
| Bereich | Zweck |
|---|---|
| 10.42.0.0/16 | Pod-IPs (Flannel), TECH |
| 10.43.0.0/16 | Service-ClusterIPs, TECH |
| 10.44.0.0/16 / 10.45.0.0/16 | Pod-/Service-Netz ENTW |
| 10.46.0.0/16 / 10.47.0.0/16 | Pod-/Service-Netz PROD |
| 10.43.0.10 | CoreDNS-ClusterIP |
Ingress — Traefik
k3s bündelt Traefik als Default-Ingress-Controller und bindet die Host-Ports 80 und 443 (je Cluster eine eigene Instanz; die Version folgt der k3s-Version).
# Traefik-Pods
kubectl get pods -n kube-system -l app.kubernetes.io/name=traefik
# Traefik-Service (zeigt NodePort-Mapping)
kubectl get svc -n kube-system traefik
# Traefik-Dashboard (aus Sicherheitsgründen standardmäßig deaktiviert)
kubectl port-forward -n kube-system svc/traefik 9000:9000
# Dann http://localhost:9000/dashboard/ öffnen
Standard-Kubernetes-Ingress (Beispiel):
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: my-app
namespace: my-app
annotations:
traefik.ingress.kubernetes.io/router.entrypoints: web
spec:
ingressClassName: traefik
rules:
- host: my-app.tech.homeserver
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: my-app-svc
port:
number: 80
Traefik-IngressRoute (native CRD):
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
name: my-app
namespace: my-app
spec:
entryPoints:
- web
routes:
- match: Host(`my-app.tech.homeserver`)
kind: Rule
services:
- name: my-app-svc
port: 80
Prometheus-Metriken (traefik_*, u.a. für "User Requests"-Panels in Grafana):
Aktiviert/konfiguriert über argocd/apps/tech/traefik-config/helmchartconfig.yaml
(k3s' HelmChartConfig-CRD) + vmservicescrape.yaml. Der Metrics-Port (9100)
läuft bewusst NICHT über den Haupt-Service traefik (der ist nur web/websecure,
extern per LoadBalancer erreichbar) — dafür rendert
metrics.prometheus.service.enabled: true einen zusätzlichen, rein
clusterinternen ClusterIP-Service traefik-metrics, an dem der
VMServiceScrape hängt. Ohne diesen dedizierten Service bleiben ALLE
früheren, automatisch generierten Pro-App-Dashboards (inzwischen entfernt; Grafana-Ordner Plattform/Anwendungen (TECH),
ConfigMaps dashboard-app-* im Namespace monitoring) bei "User
Requests"/"Fehlerrate"/"Latenz" auf "No data" stehen, weil deren Queries auf
traefik_service_requests_total{service=~"^<namespace>-.*"} matchen — siehe 60040 (Incident 2026-09-15).
# Prüfen ob traefik_* Metriken überhaupt ankommen
kubectl -n monitoring port-forward svc/vmsingle-monitoring-victoria-metrics-k8s-stack 8428:8428 &
curl -s 'http://localhost:8428/api/v1/query?query=count(traefik_service_requests_total)'
# Dedizierten Metrics-Service prüfen
kubectl -n kube-system get svc traefik-metrics
Helm-Integration
Helm wird vom Ansible-Playbook unter /usr/local/bin/helm installiert.
# Helm verifizieren
helm version
# Installierte Releases auflisten
helm list -A
# Release-Values anzeigen
helm get values argocd -n argocd
# Release upgraden
helm upgrade argocd argo/argo-cd -n argocd -f /tmp/my-values.yaml
# Release deinstallieren
helm uninstall argocd -n argocd
# Charts suchen
helm search repo traefik
helm search hub prometheus
# Repo hinzufügen
helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
helm repo update
k3s upgraden
Im TECH-Cluster steht die Version in group_vars/k3s_servers.yml und group_vars/k3s_agents.yml (nicht in all.yml). Nach der Änderung make k3s-upgrade-check, dann make k3s-upgrade: erst controlplane-0, dann controlplane-1 (jeweils nur bei gesundem Peer), dann die Agents. Alle Server brauchen dieselbe Version. Die folgende Beschreibung gilt für einen einzelnen Server (prod-vm, entw-vm).
Zum Upgrade k3s_version in capulus-ansible/group_vars/all.yml setzen und das Playbook neu laufen lassen:
# In capulus-ansible/group_vars/all.yml
k3s_version: v1.30.1+k3s1
# Nur die k3s-Rolle ausführen
make k3s
# oder:
ansible-playbook -i inventory/hosts.yml site.yml --tags k3s --ask-vault-pass
Alternativ manuell auf dem Server:
# Aktuelle Version
k3s --version
# Upgrade via Install-Skript (idempotent, upgraded bei abweichender Version)
curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION=v1.30.1+k3s1 sh -s - server
# Verifizieren
kubectl get nodes
k3s --version
Vor dem Upgrade:
- k3s-Releases auf Breaking Changes prüfen.
- Kubernetes-Changelog auf API-Deprecations prüfen.
/etc/rancher/k3s/und/var/lib/rancher/k3s/sichern.
k3s-Service-Management
# Status
sudo systemctl status k3s
# Start/Stop/Restart
sudo systemctl start k3s
sudo systemctl stop k3s
sudo systemctl restart k3s
# k3s-Logs
sudo journalctl -u k3s -f
sudo journalctl -u k3s --since "10 minutes ago"
# k3s-Kernel-Anforderungen prüfen
sudo k3s check-config
Backup & Restore
Seit der Umstellung auf embedded etcd (siehe 400a0) sichert k3s den Datastore als etcd-Snapshot. Die SQLite-Anweisungen unten gelten für die Zeit davor und für
prod-vmundentw-vm.
sudo k3s etcd-snapshot save --name manuell
sudo k3s etcd-snapshot ls
Geplante Snapshots laufen alle 6 Stunden nach /var/lib/rancher/k3s/server/db/snapshots (Retention 28 pro Server), ein Timer kopiert sie auf die NAS. Wiederherstellung bei zwei Servern: k3s auf beiden stoppen, auf controlplane-0 sudo k3s server --cluster-reset --cluster-reset-restore-path=<Snapshot>, k3s starten, auf controlplane-1 sudo rm -rf /var/lib/rancher/k3s/server/db/ und starten. Fällt ein Server dauerhaft aus, hat der andere kein Quorum: dort sudo k3s server --cluster-reset, der Ersatz tritt neu bei.
k3s nutzt SQLite als Datastore (auf dem Control-Plane-Node homeserver).
Im Multi-Node-Betrieb läuft die SQLite-DB weiterhin nur auf homeserver.
# SQLite-DB sichern
sudo cp /var/lib/rancher/k3s/server/db/state.db ~/k3s-backup-$(date +%Y%m%d).db
# Komplettes k3s-Config + Certs sichern
sudo tar -czf ~/k3s-backup-$(date +%Y%m%d).tar.gz \
/etc/rancher/k3s/ \
/var/lib/rancher/k3s/server/
# Alle YAML-Manifests exportieren (GitOps-Alternative)
kubectl get all -A -o yaml > ~/k8s-resources-backup-$(date +%Y%m%d).yaml
Für kritische Daten ist GitOps der bevorzugte Weg — alle Application-Definitionen
liegen im Git-Repo, ein erneuter Playbook-Run + ArgoCD-Sync stellt den Cluster
in den gewünschten Zustand zurück.
Fehlersuche
Erste Diagnose auf dem Node (homeserver für TECH, prod-vm für PROD, entw-vm für ENTW):
sudo systemctl status k3s # auf Workern: k3s-agent
sudo journalctl -u k3s -n 100 --no-pager
kubectl get nodes -o wide
kubectl get pods -A | grep -v -e Running -e Completed
kubectl get events -A --sort-by=.lastTimestamp | tail -30
| Symptom | Ursache | Lösung |
|---|---|---|
kubectl meldet The connection to the server … was refused |
k3s läuft nicht, falsche kubeconfig oder falscher Kontext | systemctl status k3s, kubectl config current-context, Zugriff je Cluster: a0010 |
Worker bleibt NotReady oder fehlt |
Worker ist aus (nachts gewollt, Cluster Power Manager), k3s-agent läuft nicht, Netz/Tailscale |
journalctl -u k3s-agent -n 100 auf dem Worker, Rolle k3s_agent, Tailscale |
Worker tritt nicht bei (Unauthorized, x509) |
Join-Token oder Server-URL falsch | Token in den Ansible-Variablen prüfen, --tags k3s-agent neu ausrollen |
Pods Pending mit FailedScheduling |
Ressourcen, Node-Selektor, Taints, PVC ungebunden | kubectl describe pod, Node-Auslastung kubectl top nodes, Abschnitt „Storage“ oben |
PVC Pending |
WaitForFirstConsumer ohne geplanten Pod, StorageClass fehlt, NAS nicht erreichbar |
kubectl get sc, kubectl describe pvc, NAS-Speicher |
Pods erreichen sich nicht (no route to host, Timeouts zwischen Nodes) |
Flannel/VXLAN, Firewall (UDP 8472), Tailscale-Interface | kubectl -n kube-system get pods -l app=flannel bzw. journalctl -u k3s, Firewall der Hosts |
| Pods lösen Namen nicht auf | CoreDNS, coredns-custom |
CoreDNS-Erweiterung |
| Ingress liefert 404 oder Zertifikatsfehler | Traefik-Konfiguration, Zertifikat | Traefik-Konfiguration, Internes TLS |
LoadBalancer-IP bleibt <pending> |
MetalLB | MetalLB |
kubectl top meldet Metrics API not available |
metrics-server nicht bereit | kubectl -n kube-system get pods -l k8s-app=metrics-server |
| k3s startet nach Upgrade nicht | Konfigurationsdatei (/etc/rancher/k3s/config.yaml) fehlerhaft, Kernel-Anforderungen |
journalctl -u k3s -n 200, k3s check-config, Abschnitt „k3s upgraden“ |
| Datenbank/Zertifikate beschädigt oder Cluster verloren | Datenträger- oder VM-Defekt | Abschnitt „Backup & Restore“, Incident 50010 für den Ablauf einer Wiederherstellung samt Sealed-Secrets-Schlüssel |
Weitere Anlaufstellen: Host-Troubleshooting, zentrale Fehlersuche.