Deep Dive: K3s – een complete Kubernetes in één binary, wat hij weglaat en zes dingen die hij niet vanzelf deed

Wat er in de ene K3s-binary draait, wat deze setup uitzet of vervangt, hoe een cluster met één node zonder verrassingen wordt geüpgraded – en zes defaults en gaten die pas in de echte praktijk opdoken.

Illustratie bij de Deep Dive-serie

🌐 Ook in: English · Deutsch · Français · Español · Italiano · Português · Polski

Deep Dive in de serie rond de Ansible Tour. De tour legt de roles uit, de deep dives de techniek eronder: hoe het werkt, waarom het hier zo wordt gebruikt en wat er onderweg misging.

K3s is gecertificeerde Kubernetes in één binary van zo’n 70 MB. API server, scheduler, controller manager, kubelet, kube-proxy, containerd, Flannel, CoreDNS en een network-policy-controller starten allemaal vanuit één proces en één systemd-unit. Dat maakt hem de voor de hand liggende keuze voor een cluster van precies één node – en het verbergt veel. Deze post legt uit wat er echt in die binary draait, wat deel 2 van de tour configureert, en zes dingen die K3s niet vanzelf deed en die pas in bedrijf werden gevonden.

Inhoud

🧭 Wat er in de binary zit

Eén supervisor, veel componenten

k3s server is een supervisor. Hij start de Kubernetes-control-plane-componenten als goroutines binnen zijn eigen proces – API server, scheduler, controller manager – en daarnaast de node-componenten: de kubelet, kube-proxy, de Flannel-CNI en een ingebouwde network-policy-controller (code uit kube-router). containerd draait als apart childproces met een eigen socket onder /run/k3s/containerd/. Alles deelt één logstroom in de journal (journalctl -u k3s) en één versienummer.

De datastore: SQLite in plaats van etcd

Upstream Kubernetes bewaart zijn state in etcd. Een K3s met één node gebruikt SQLite via kine, een shim die de etcd-API naar SQL vertaalt. De hele clusterstate – elke Deployment, Secret, ConfigMap, elk event – staat in /var/lib/rancher/k3s/server/db/state.db: 24 MB op de blog, 23 MB op een Nextcloud-server, plus een write-ahead log van 20 MB. Met meer dan één servernode schakelt K3s over op ingebouwde etcd.

containerd, de CRI en de pause-container

De kubelet praat met containerd via de Container Runtime Interface. Voor elke pod start containerd eerst een piepklein pause-containertje dat de network namespace van de pod vasthoudt; de echte containers sluiten daarbij aan. k3s crictl is de CRI-client om rechtstreeks op dat niveau te kijken – pods, containers, images – zonder via de API server te gaan. K3s gebruikt cgroup v2 op AlmaLinux 9, dus de resourcelimieten van de pod zijn gewone cgroup-bestanden onder /sys/fs/cgroup/kubepods.slice/.

Netwerk: Flannel, kube-proxy, de policy-controller

  • Flannel geeft elke pod een adres uit 10.42.0.0/16 (op één node: één /24), maakt een bridge cni0 en per pod een veth-paar. Backend hier: VXLAN – irrelevant op één node, maar de default voor een tweede.
  • kube-proxy maakt van Services iptables-regels (via iptables-nft, in nftables-tabellen): ClusterIP-DNAT, NodePorts, load balancing over endpoints.
  • De network-policy-controller maakt van NetworkPolicies chains (KUBE-ROUTER-*, KUBE-NWPLCY-*, één KUBE-POD-FW-* per pod). Hij hoort bij de binary en staat standaard aan. Onthoud deze.

Certificaten en tokens

K3s maakt bij de eerste start zijn eigen CA en alle certificaten aan (/var/lib/rancher/k3s/server/tls/), een jaar geldig, en vernieuwt ze automatisch als de service binnen 90 dagen voor het verlopen start. De admin-kubeconfig is /etc/rancher/k3s/k3s.yaml; de node-token in /var/lib/rancher/k3s/server/token is wat een tweede node nodig zou hebben om erbij te komen.

🛡️ Waarom hij hier staat

  • Kubernetes-semantiek op één kleine server. Deployments met rolling- of recreate-updates, probes die een vastgelopen container herstarten, NetworkPolicies tussen pods, resourcelimieten, een admission policy voor images – zonder een control-plane-cluster te draaien.
  • Eén binary, één unit, één vastgepinde versie. Het hele platform is reproduceerbaar vanuit Ansible; een upgrade is “binary vervangen, unit herstarten”.
  • Goede ondersteuning voor AlmaLinux en SELinux: een onderhouden SELinux-policy (k3s-selinux) en containerd met SELinux-labeling.

🔧 Wat deze repository doet

config.yaml: wat uit gaat, wat aan gaat

De meeste argumenten komen uit de CIS Kubernetes benchmark: een API-auditlog met rotatie, EventRateLimit zodat een crashloopende pod de API niet met events overspoelt, een PID-limiet per pod tegen fork bombs. Eén aanbeveling wordt bewust niet gevolgd: AlwaysPullImages zou elke image bij elke podstart uit de registry trekken – ook de WordPress-cronpod elke vijf minuten – en een korte registry-storing overal in falende pods veranderen, voor een multi-tenant-bescherming die een single-tenant-cluster niet nodig heeft.

Vastgepind, en in twee stappen geïnstalleerd

De binary komt uit de GitHub-release van k3s_version (versions.yml), het installscript van dezelfde tag – niet van get.k3s.io, dat altijd het nieuwste script serveert en op de dag dat de tweede Nextcloud-server werd opgezet een tijdlang HTTP 500 antwoordde. Het script draait met INSTALL_K3S_SKIP_DOWNLOAD=true, alleen om de unit aan te maken. Rond K3s installeert de role Helm, cert-manager met een Let’s Encrypt-ClusterIssuer en de F5 nginx-ingress-controller, en patcht hij elke default-ServiceAccount zodat pods geen API-token meer krijgen dat ze nooit gebruiken (CIS 5.1.5). De applicatieroles voegen per namespace een ValidatingAdmissionPolicy toe die pods weigert waarvan de images niet uit een toegestane lijst registries komen – sinds Kubernetes 1.30 ingebouwd in de API server, geen extra component.

Het upgradepad

  1. Lees de draaiende versie (k3s --version).
  2. Als die afwijkt van de pin: download de binary met get_url, force: true.
  3. restorecon op de binary.
  4. Flush de handlers meteen – de herstart gebeurt hier, niet aan het eind van de play.
  5. Wacht tot kubectl get nodes antwoordt en ga dan verder met de roles die in het cluster deployen.
  6. Aan het eind van de run vergelijkt common_version_active de kubelet-versie die de API meldt met de pin.

Stappen 2, 3 en 6 bestaan elk vanwege een fout, zie hieronder.

🐛 Zes dingen die K3s niet vanzelf deed

1. De upgrade die niets deed

Tot 19 oktober 2026 had de downloadtask geen force. Ansible’s get_url slaat de download dan over als het doelbestand al bestaat – dus elke versieverhoging sinds de eerste installatie was op de bestaande hosts stilletjes een no-op geweest. Het kwam boven omdat de drift check voor v1.37.1 voor K3s helemaal geen wijziging liet zien. Sindsdien leest de smoke test aan het eind van elke run (common_version_active) de versie die de kubelet echt meldt, niet die uit de inventory.

De les: een updatetask die klaar is, heeft niet per se iets geüpdatet. Na een versieverhoging telt de versie die de kubelet meldt.

2. Pods die SELinux niet insloot

SELinux stond op alle hosts op enforcing en de HostPath-directory’s droegen container_file_t. Maar K3s start containerd alleen met SELinux-ondersteuning als zijn configuratie selinux: true zegt – en dat deed die niet. Elke pod draaide als spc_t of unconfined_service_t, die SELinux helemaal niet beperkt. Sinds 19 oktober 2026 staat de optie aan en is de k3s-selinux-policy geïnstalleerd; elke pod draait nu als container_t met eigen MCS-categorieën, en pods die al vóór de omschakeling bestonden moesten opnieuw worden aangemaakt om het op te pikken. De SELinux-deep-dive vertelt het hele verhaal.

3. Een nieuwe binary met het verkeerde label

get_url schrijft via een tijdelijk bestand en hernoemt dat. De nieuwe binary krijgt daardoor het label van zijn directory (bin_t) in plaats van container_runtime_exec_t uit de policy, en K3s zou in het verkeerde domein starten. Een restorecon na elke download lost dat op.

De les: SELinux op de host betekent niet SELinux in de container. De runtime moet het expliciet gebruiken, en elke nieuw gedownloade binary heeft daarna zijn juiste label nodig.

4. De policy-engine die nooit nodig was

Twee maanden lang draaide Calico naast K3s als vermeende NetworkPolicy-engine. Hij dwong niets af – Calico’s Felix behandelt alleen interfaces met de naam cali*, Flannel maakt veth* aan – en alle handhaving kwam al die tijd van de eigen controller van K3s. Het bewijs was onaangenaam: met de controller voor een test uitgeschakeld (disable-network-policy) bereikte een pod in de namespace default MariaDB op poort 3306. Calico is weg, en de configuratie draagt nu een commentaar in hoofdletters: schakel de ingebouwde controller nooit uit. De nftables-deep-dive beschrijft de firewallkant.

De les: een component waarvan het effect nooit is getest, is alleen maar ballast – en een reden om je veilig te voelen zonder het te zijn.

5. Een admission-flag die verving in plaats van toevoegde

In upstream Kubernetes voegt --enable-admission-plugins plugins toe aan de standaardlijst. In K3s vervangt hij de eigen lijst van K3s. Hem op alleen EventRateLimit zetten liet stilletjes NodeRestriction vallen – de plugin die voorkomt dat een gecompromitteerde kubelet objecten van andere nodes wijzigt. Een nieuwe kube-bench-run ving het op (CIS 1.2.14 ging van PASS naar FAIL). Beide staan nu expliciet in de lijst. Een verwante valkuil: de API server maakt de directory van zijn auditlog niet aan en weigert zonder die directory te starten; de role maakt hem aan vóór de herstart.

De les: een flag met dezelfde naam kan in K3s iets anders doen dan in Kubernetes. De documentatie van de distributie geldt, en een nieuwe kube-bench-run na elke wijziging laat zien of er iets verloren is gegaan.

📊 Gemeten

BlogNextcloud-server
K3s-versiev1.37.1+k3s1v1.37.1+k3s1
Pods1714
Geheugen van k3s server (RSS)789 MB826 MB
containerd (RSS)202 MB190 MB
CPU-tijd van k3s server23 min in 7,5 u (≈ 5 % van een core)2,5 u in 9,5 u (≈ 26 % van een core)
Datastore (state.db + WAL)24 + 20 MB23 + 20 MB
API-auditlog vóór 20 okt 20261,1 GB (op de ingestelde limiet)1,0 GB, ~230 MB/dag
API-auditlog na de policywijziging–~28 MB/dag

Ongeveer een gigabyte RAM voor de hele control plane is de prijs van “echte Kubernetes op één node”. Twee getallen vielen op. De auditlog zat op zijn limiet van tien backups van 100 MB – de rotatie werkte, maar de “30 dagen” uit de configuratie waren in werkelijkheid vierenhalf. En op de Nextcloud-server gebruikte de control plane vijf keer de CPU van de blog, met minder pods.

Zeven, geen bug: hetzelfde werk tegen vijf keer de kosten

De auditlog liet op alle drie de servers dezelfde schrijflast zien, en een CPU-profiel van 30 seconden – zonder herstart genomen via /debug/pprof van de kubelet, dat het hele K3s-proces profileert – liet geen enkele boosdoener zien: alles was ongeveer vierenhalf keer zo duur, vooral de Go-scheduler die goroutines wekt en de system calls daarachter. Go beperken tot vier threads (GOMAXPROCS=4) veranderde niets. Het antwoord stond in /sys/devices/system/cpu/vulnerabilities/: de Nextcloud-servers draaien op een oudere AMD EPYC-generatie die door Retbleed is getroffen, en de kernel beschermt elke return uit een kernelfunctie met een “return thunk”. Voor een programma dat leeft van system calls en context switches kost dat veel; de nieuwere CPU van de blog is “not affected”. De mitigatie uitzetten op een gedeelde virtuele machine zou onverstandig zijn – ongeveer 2,6 % van een server met acht cores is de prijs.

Zes: een auditlog die verdronk in zijn eigen ruis

Een uitsplitsing van één bestand van 100 MB liet zien waar het volume vandaan kwam: lease-heartbeats van de leader elections en de kubelet (23 %), health-, discovery- en OpenAPI-requests (14 %), de API server die met zichzelf praat (12 %), en read-only-requests van de eigen componenten van het platform, service accounts en nodes (ongeveer 40 %). Niets daarvan heeft beveiligingswaarde; het duwde alleen de interessante entries uit het bewaarvenster. De policy laat nu precies deze vallen – met twee regels bewust vóór de dropregel: het lezen van secrets blijft voor elke lezer gelogd, en alles wat een beheerder doet blijft gelogd. Een simulatie tegen het echte bestand voorspelde dat er 10 % over zou blijven; na de uitrol groeide de log met zo’n 28 MB per dag in plaats van 230.

Upgrades

Eén minorversie tegelijk, zoals Kubernetes vereist (1.36 → 1.37, niet 1.35 → 1.37). Verhoog k3s_version in versions.yml, draai de drift check (--check --diff) – die moet nu de download van de binary tonen –, draai het playbook en lees het versierapport aan het eind. Een herstart van K3s herstart noch de pods noch de containers van containerd; de API is zo’n 20 seconden weg, de websites niet.

Backups – en wat er echt nodig is

De datastore wordt hier bewust niet gebackupt. Elk object erin wordt door Ansible aangemaakt uit de repository en de vault: namespaces, Secrets, Deployments, policies. De data die ertoe doet staat buiten het cluster in HostPath-directory’s en in de databases, en die worden elke nacht door de backupserver opgehaald. Een server herstellen betekent dus: AlmaLinux installeren, het playbook draaien, de datadirectory’s terugzetten. Het cluster zelf is wegwerpbaar – het sterkste argument om alles in code te houden.

🆘 Spiekbriefje: symptoom → commando

De korte versie van dit artikel voor het moment dat er iets mis is. Uitvoeren op de host als root; <…> zijn placeholders.

SymptoomCommando
Een pod start nietk3s kubectl get pods -A
k3s kubectl -n <ns> describe pod <pod>
Waarom crashte een container?k3s kubectl -n <ns> logs <pod> -c <container> --previous
Wat is er recent gebeurd?k3s kubectl get events -A --sort-by=.lastTimestamp | tail -20
kubectl hangt of de node is NotReadysystemctl status k3s
journalctl -u k3s --since -15min
k3s crictl ps # containerd, without the API server
Wie gebruikt CPU en geheugen?k3s kubectl top pods -A
Gewijzigde ConfigMap of Secret niet actiefk3s kubectl -n <ns> rollout restart deployment/<name>
Schijf loopt vol met oude imagesk3s crictl rmi --prune
Pod geblokkeerd door SELinux?ausearch -m AVC -ts recent | grep container_t
ps -eZ | grep container_t | head
Wanneer verlopen de certificaten?openssl x509 -enddate -noout -in /var/lib/rancher/k3s/server/tls/serving-kube-apiserver.crt

🎯 De lessen

  • Controleer na een update de draaiende versie, niet de melding van de task.
  • Containers zijn alleen ingesloten als de runtime SELinux gebruikt; ps -eZ laat het zien.
  • Kennis over Kubernetes-flags geldt niet automatisch voor K3s.
  • Een auditlog heeft een policy nodig die de ruis weglaat, anders duwt de ruis de entries die ertoe doen eruit.
  • Back alleen up wat niet uit de repository opnieuw kan worden gemaakt.

⚖️ Alternatieven – en waarom K3s

OptieSterk puntWaarom niet hier
kubeadmUpstream Kubernetes, niets verborgenetcd, de control-plane-componenten en de CNI moet je zelf apart draaien en upgraden – veel voor één node.
k0sOok één binary, nette defaultsVergelijkbaar; K3s heeft de onderhouden SELinux-policy en meer documentatie voor AlmaLinux.
MicroK8sMakkelijke add-onsVerspreid als snap – niet thuis op AlmaLinux.
Docker/Podman ComposeVeel eenvoudigerGeen probes met herstart, geen NetworkPolicies, geen admission policy, geen rolling updates.
K3sVolledige Kubernetes-API, kleinste footprint, SELinux-policyGekozen.

K3s houdt zijn belofte: echte Kubernetes in één binary. Wat de afgelopen weken lieten zien, is dat “één binary” ook “één plek waar defaults zich verstoppen” is. Vier van de zes problemen hierboven waren geen bugs in K3s, maar defaults en aannames – SELinux uit tenzij je erom vraagt, een admission-flag die vervangt in plaats van toevoegt, een policy-controller die er al was, en onze eigen vang-alles-auditregel die elke heartbeat logde. Elk ervan staat nu als commentaar in de role, naast de regel die het zou terugbrengen.

Sommige teksten en afbeeldingen op deze site zijn met hulp van AI gemaakt of door AI gegenereerd. Details