PKR-Lab

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-0 heißt controlplane-1, ist k3s-Server mit embedded etcd (zusammen mit homeserver) 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:

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-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-vm und entw-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.