Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 2: k3s verstehen

Ziel: k3s mit einem Befehl auf einer VM installieren, verstehen, was in dem einen Binary steckt, und notes mit Images aus Rancher Desktop über Traefik erreichbar machen. · Dauer: ca. 60 min · Voraussetzung: Tag 1

Briefing

  • k3s ist die schlanke Kubernetes-Distribution von Rancher: ein Binary von knapp 80 MB mit Control Plane, kubelet, containerd und Werkzeugen. Im Kern steckt dasselbe k3s, das Rancher Desktop auf dem Mac betreibt.
  • Statt etcd speichert ein einzelner k3s-Server den Zustand in SQLite. Für mehrere Server gibt es eingebettetes etcd.
  • k3s bringt mit: Traefik als Ingress-Controller, ServiceLB für Services vom Typ LoadBalancer, local-path für Volumes und einen NetworkPolicy-Controller.
  • Die VM k3s aus diesem Tag nimmt Rancher an Tag 4 unter seine Verwaltung.
 Mac                               VM k3s (Ubuntu 24.04)
 ┌─────────────────────────┐       ┌──────────────────────────────────────┐
 │ Rancher Desktop         │ .tar  │ k3s (ein Binary, Dienst k3s)         │
 │  nerdctl save ──────────┼──────►│  containerd ◄─ k3s ctr images import │
 │ kubectl, helm ──────────┼─:6443►│  API-Server, SQLite state.db         │
 │ curl notes.<IP>.sslip.io┼──:80─►│  Traefik ─► web ─► api ─► db         │
 └─────────────────────────┘       └──────────────────────────────────────┘

Drill 1: Die VM

multipass launch 24.04 --name k3s --cpus 2 --memory 3G --disk 20G
source ~/rancher-lab/setup/env.sh
cat > "$LAB/setup/vms.env" <<EOF
# setup/vms.env – Adressen der VMs (Tag 2, ergänzt an Tag 3 und 5)
export K3S=$(multipass info k3s --format json | jq -r '.info.k3s.ipv4[0]')
EOF
source "$LAB/setup/env.sh"
echo "$K3S"

Erwartet (gekürzt, Namen, IPs und Zeiten weichen bei dir ab):

Launched: k3s
…

env.sh liest vms.env mit ein. Ab jetzt kennt jede neue Shell die Adresse, sobald du env.sh sourcest.

Fortschritt speichern? Kostenlos registrieren

Drill 2: k3s installieren

Der Installer lädt das Binary, legt den Dienst k3s an und startet ihn. Die Version steht fest im Befehl:

multipass exec k3s -- bash -c \
  'curl -sfL https://get.k3s.io | sudo INSTALL_K3S_VERSION=v1.36.5+k3s1 sh -'
multipass exec k3s -- k3s --version
multipass exec k3s -- sudo k3s kubectl get nodes -o wide

Erwartet (gekürzt):

[INFO]  systemd: Creating service file /etc/systemd/system/k3s.service
[INFO]  systemd: Enabling k3s unit
Created symlink /etc/systemd/system/multi-user.target.wants/k3s.service → …
[INFO]  systemd: Starting k3s
k3s version v1.36.5+k3s1 (3dd98cc5)
go version go1.26.8
NAME   STATUS   ROLES           AGE   VERSION        …   CONTAINER-RUNTIME
k3s    Ready    control-plane   36s   v1.36.5+k3s1   …   containerd://2.3.4-k3s1.36

Nach einer halben Minute läuft ein ganzes Cluster. Steht direkt nach dem Installer noch No resources found da, meldet sich der Node gerade erst an; ein paar Sekunden später ist er Ready.

Fortschritt speichern? Kostenlos registrieren

Drill 3: Was im Binary steckt

multipass exec k3s -- bash -c 'ls -la /usr/local/bin | grep -E "k3s|kubectl|ctr"'
multipass exec k3s -- sudo ls /var/lib/rancher/k3s/server/db
multipass exec k3s -- sudo ls /var/lib/rancher/k3s/server/manifests
multipass exec k3s -- sudo k3s kubectl get pods -n kube-system

Erwartet (gekürzt):

lrwxrwxrwx  1 root root        3 … crictl -> k3s
lrwxrwxrwx  1 root root        3 … ctr -> k3s
-rwxr-xr-x  1 root root 79077538 … k3s
-rwxr-xr-x  1 root root     2318 … k3s-killall.sh
-rwxr-xr-x  1 root root     3189 … k3s-uninstall.sh
lrwxrwxrwx  1 root root        3 … kubectl -> k3s
state.db
state.db-shm
state.db-wal
ccm.yaml
coredns.yaml
local-storage.yaml
metrics-server
rolebindings.yaml
runtimes.yaml
traefik.yaml
NAME                                      READY   STATUS      RESTARTS      AGE
coredns-7cfb7bc9c7-pkm72                  1/1     Running     0             10m
helm-install-traefik-crd-c772p            0/1     Completed   0             10m
helm-install-traefik-kvx5z                0/1     Completed   2 (10m ago)   10m
local-path-provisioner-77b9867795-ckcbx   1/1     Running     0             10m
metrics-server-6dc596dfb8-vsl8r           1/1     Running     0             10m
svclb-traefik-44d8b4d7-r6l49              2/2     Running     0             9m47s
traefik-7c8544f77-2bft9                   1/1     Running     0             9m47s

kubectl, crictl und ctr sind nur Verweise auf k3s. Je nach Aufrufnamen verhält sich das Binary anders. Der ganze Zustand des Clusters liegt in einer SQLite-Datei. Die Dateien in manifests spielt k3s beim Start automatisch ein; so kommen Traefik und local-path ins Cluster. RKE2 macht das genauso („Kubernetes zum Anfassen”, Tag 12).

Fortschritt speichern? Kostenlos registrieren

Drill 4: kubectl vom Mac

mkdir -p "$LAB/kube"
multipass exec k3s -- sudo cat /etc/rancher/k3s/k3s.yaml \
  | sed -e "s/127.0.0.1/$K3S/" -e 's/: default$/: k3s/' > "$LAB/kube/k3s.yaml"
chmod 600 "$LAB/kube/k3s.yaml"
export KUBECONFIG="$LAB/kube/k3s.yaml"
kubectl get nodes

Erwartet:

NAME   STATUS   ROLES           AGE   VERSION
k3s    Ready    control-plane   39s   v1.36.5+k3s1

Jedes Cluster dieses Buchs bekommt eine eigene Datei unter ~/rancher-lab/kube/. Welches Cluster gemeint ist, entscheidet KUBECONFIG, nicht ein versehentlich gewechselter Kontext.

Fortschritt speichern? Kostenlos registrieren

Drill 5: Images aus Rancher Desktop

Die VM hat keine Registry. Die Images aus Tag 1 wandern als Archiv hinüber und werden in den containerd von k3s importiert:

nerdctl --namespace k8s.io save -o notes-images.tar \
  notes-api:0.2.0 notes-web:0.1.0 notes-worker:0.1.0
multipass transfer notes-images.tar k3s:/tmp/
multipass exec k3s -- sudo k3s ctr images import /tmp/notes-images.tar
multipass exec k3s -- sudo k3s crictl images | grep notes
multipass exec k3s -- rm /tmp/notes-images.tar
rm notes-images.tar

Erwartet (gekürzt):

…
docker.io/library/notes-api      0.2.0      ec38f50335a8c   4.5MB
docker.io/library/notes-web      0.1.0      d50e082fcd584   64.2MB
docker.io/library/notes-worker   0.1.0      2f668f81849cf   45.5MB

Kurze Namen wie notes-api ergänzt containerd zu docker.io/library/notes-api. Darum findet das Chart die Images, obwohl sie nie auf Docker Hub lagen. Die Images sind arm64 wie deine VM; ein Mac mit Apple-Chip baut sie passend.

Fortschritt speichern? Kostenlos registrieren

Drill 6: notes auf k3s

Erst die Plattform (Namespace mit Pod Security, Quota, ServiceAccount notes) und die Secrets, dann das Chart. Ohne den ServiceAccount entstehen gar keine Pods (Tag 1).

mkdir -p "$LAB/tag02" && cd "$LAB/tag02"
cp "$LAB/code/tag02/"* .
kubectl apply -f "$LAB/code/platform/namespace.yaml"
kubectl -n notes create secret generic notes-api --from-literal=api-key=lab-api-key-123
kubectl -n notes create secret generic notes-db --from-literal=password=lab-db-pw-123 \
  --from-literal=db-url='postgres://notes:lab-db-pw-123@db:5432/notes'
cat values-k3s.yaml

Erwartet (gekürzt):

namespace/notes created
limitrange/defaults created
resourcequota/notes created
serviceaccount/notes created
secret/notes-api created
secret/notes-db created
# tag02/values-k3s.yaml – Stand Ende Tag 2: notes auf k3s
gateway:
  enabled: false        # kein Envoy Gateway, Traefik aus k3s übernimmt (ingress.yaml)
networkPolicy:
  gatewayNamespace: kube-system   # dort läuft Traefik

Das Chart aus „Kubernetes zum Anfassen” bringt ein Gateway für Envoy mit. k3s hat Traefik, also schaltest du das Gateway ab und lässt in der NetworkPolicy den Namespace von Traefik zu:

helm -n notes install notes "$LAB/code/notes-chart/notes" -f values-k3s.yaml \
  --wait --timeout 5m | grep -E '^(NAME|STATUS):'
kubectl -n notes get pods

Erwartet (gekürzt):

NAME: notes
STATUS: deployed
NAME                      READY   STATUS      RESTARTS      AGE
api-65dfff884-4w7h8       1/1     Running     4 (63s ago)   105s
api-65dfff884-fgp28       1/1     Running     4 (64s ago)   105s
api-65dfff884-mngv7       1/1     Running     4 (61s ago)   105s
db-0                      1/1     Running     0             104s
migrate-q2s75             0/1     Completed   1 (4s ago)    6s
web-7fd8cd6fd9-fmxwj      1/1     Running     0             106s
web-7fd8cd6fd9-kz87m      1/1     Running     0             105s
worker-666579f9d5-xk57l   1/1     Running     0             105s

Die Installation dauert knapp zwei Minuten. Die api startet neu, bis Postgres bereit ist, wie im Schwesterbuch.

Fortschritt speichern? Kostenlos registrieren

Drill 7: Über Traefik erreichbar

# tag02/ingress.yaml – Stand Ende Tag 2: web über das Traefik von k3s
# Vorlage: K3S_IP ersetzt Drill 7 per sed durch die Adresse der VM k3s.
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: web
  namespace: notes
spec:
  ingressClassName: traefik
  rules:
    - host: notes.K3S_IP.sslip.io
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: web
                port:
                  number: 3000

sslip.io ist ein öffentlicher DNS-Dienst: notes.192.168.64.5.sslip.io löst auf 192.168.64.5 auf. So bekommt jede VM ohne eigenes DNS einen Hostnamen.

sed "s/K3S_IP/$K3S/" ingress.yaml | kubectl apply -f -
kubectl -n notes get ingress
kubectl -n kube-system get svc traefik
curl -s "http://notes.$K3S.sslip.io/api/notes"; echo
curl -s -X POST -H 'Content-Type: application/json' -d '{"text":"läuft auf k3s"}' \
  "http://notes.$K3S.sslip.io/api/notes"; echo

Erwartet (gekürzt):

ingress.networking.k8s.io/web created
NAME   CLASS     HOSTS                  ADDRESS   PORTS   AGE
web    traefik   notes.….sslip.io       …         80      1s
NAME      TYPE           CLUSTER-IP    EXTERNAL-IP   PORT(S)                      AGE
traefik   LoadBalancer   10.43.17.55   …             80:31126/TCP,443:31116/TCP   7m50s
[]
{"id":"395a46da-…","text":"läuft auf k3s"}

Traefik ist ein Service vom Typ LoadBalancer, und ServiceLB gibt ihm die IP der VM als EXTERNAL-IP. Dafür läuft der Pod svclb-traefik-… auf jedem Node und leitet Port 80 und 443 an Traefik weiter. Ohne Cloud gäbe es sonst keine externe Adresse.

Achtung: web leitet /api/notes an die api weiter. Beim POST gehört Content-Type: application/json dazu, sonst antwortet notes mit text required.

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

kubectl get nodes

Erwartet: ein Node k3s, Ready, Version v1.36.5+k3s1.

NAME   STATUS   ROLES           AGE   VERSION
k3s    Ready    control-plane   12m   v1.36.5+k3s1
helm -n notes list

Erwartet: Release notes mit Chart notes-0.3.0, Status deployed.

NAME    NAMESPACE   REVISION   UPDATED   STATUS     CHART         APP VERSION
notes   notes       1          2026-…    deployed   notes-0.3.0   0.2.0
curl -s "http://notes.$K3S.sslip.io/api/notes"; echo

Erwartet: deine Notiz aus Drill 7.

[{"id":"395a46da-…","text":"läuft auf k3s"}]

Challenge

Das Chart bringt NetworkPolicies mit. Beweise, dass k3s sie auch durchsetzt: Ein Pod im Namespace default darf die api nicht erreichen, web schon.

Hinweis: kubectl run mit busybox:1.37 und wget -T 3 reicht.

Lösung

kubectl -n default run fremd --image=busybox:1.37 --restart=Never -- sleep 600
kubectl -n default wait --for=condition=Ready pod/fremd --timeout=90s
kubectl -n default exec fremd -- wget -qO- -T 3 http://api.notes:8080/version
kubectl -n notes exec deploy/web -- wget -qO- -T 3 http://api:8080/version
kubectl -n default delete pod fremd

Erwartet (gekürzt):

pod/fremd created
pod/fremd condition met
wget: can't connect to remote host (10.43.70.183): Connection refused
command terminated with exit code 1
0.2.0
pod "fremd" deleted from default namespace

k3s setzt NetworkPolicies mit einem eingebauten Controller (kube-router) durch. Er weist verbotene Verbindungen sofort ab (Connection refused). Canal in RKE2 verwirft sie stattdessen, dort endet wget im Timeout („Kubernetes zum Anfassen”, Tag 11).

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • Hochverfügbarkeit: Für mehrere Server startet k3s mit eingebettetem etcd (--cluster-init) oder nutzt eine externe Datenbank. SQLite taugt für einen Server.
  • Einsatzorte: k3s läuft dort, wo Ressourcen knapp sind: Edge, Filialen, Fahrzeuge, CI-Runner. Für Rechenzentren mit Härtungsvorgaben nimmt man eher RKE2.
  • Komponenten abwählen: disable: [traefik, servicelb] in /etc/rancher/k3s/config.yaml ersetzt sie durch eigene Lösungen, etwa einen anderen Ingress-Controller oder MetalLB.
  • Images: Ein Archiv per ctr images import ist eine Notlösung für ein Labor. Ab Tag 7 kommen die Images aus einer Registry.
  • Verwaltung: Viele k3s-Cluster verwaltet niemand per SSH. Genau dafür gibt es Rancher (ab Tag 3).