Deep Dive: K3s – cały Kubernetes w jednej binarce, co z niego wycięto i sześć rzeczy, których nie zrobił sam
Co działa w jednej binarce K3s, co ten setup wyłącza lub zastępuje, jak bez niespodzianek aktualizuje się klaster z jednym węzłem – i sześć ustawień domyślnych oraz luk, które wyszły dopiero w realnej eksploatacji.

🌐 Także w: English · Deutsch · Français · Español · Italiano · Português · Nederlands
Deep Dive z serii wokół Ansible Tour. Tour objaśnia role, deep dive’y – technikę pod spodem: jak działa, dlaczego jest tu używana właśnie tak i co po drodze poszło nie tak.
K3s to certyfikowany Kubernetes w jednej binarce o rozmiarze około 70 MB. API server, scheduler, controller manager, kubelet, kube-proxy, containerd, Flannel, CoreDNS i kontroler network policies startują z jednego procesu i jednej unitu systemd. To czyni go oczywistym wyborem dla klastra z dokładnie jednym węzłem – i sporo ukrywa. Ten wpis wyjaśnia, co naprawdę działa w tej binarce, co konfiguruje część 2 touru oraz sześć rzeczy, których K3s nie zrobił sam, a które wyszły dopiero w eksploatacji.
Spis treści
🧭 Co jest w binarce
Jeden supervisor, wiele komponentów
k3s server to supervisor. Uruchamia komponenty control plane Kubernetesa jako goroutines we własnym procesie – API server, scheduler, controller manager – a obok nich komponenty węzła: kubelet, kube-proxy, CNI Flannel i wbudowany kontroler network policies (kod z kube-router). containerd działa jako osobny proces potomny z własnym socketem w /run/k3s/containerd/. Wszystko dzieli jeden strumień logów w journalu (journalctl -u k3s) i jeden numer wersji.
Datastore: SQLite zamiast etcd
Upstreamowy Kubernetes trzyma swój stan w etcd. Jednowęzłowy K3s używa SQLite przez kine – warstwę, która tłumaczy API etcd na SQL. Cały stan klastra – każdy Deployment, Secret, ConfigMap, event – siedzi w /var/lib/rancher/k3s/server/db/state.db: 24 MB na blogu, 23 MB na serwerze Nextcloud, plus write-ahead log o rozmiarze 20 MB. Przy więcej niż jednym węźle serwerowym K3s przełącza się na wbudowane etcd.
containerd, CRI i pause container
Kubelet rozmawia z containerd przez Container Runtime Interface. Dla każdego poda containerd najpierw uruchamia malutki kontener pause, który trzyma network namespace poda; właściwe kontenery do niego dołączają. k3s crictl to klient CRI do bezpośredniego zaglądania na ten poziom – pody, kontenery, obrazy – bez przechodzenia przez API server. K3s używa cgroup v2 na AlmaLinux 9, więc limity zasobów poda to zwykłe pliki cgroup w /sys/fs/cgroup/kubepods.slice/.
Sieć: Flannel, kube-proxy, kontroler policies
- Flannel daje każdemu podowi adres z
10.42.0.0/16(na jednym węźle: jedno/24), tworzy bridgecni0i paręvethna pod. Backend tutaj: VXLAN – bez znaczenia na jednym węźle, ale domyślny dla drugiego. - kube-proxy zamienia Services na reguły iptables (przez iptables-nft, w tabelach nftables): DNAT dla ClusterIP, NodePorty, load balancing po endpointach.
- Kontroler network policies zamienia NetworkPolicies na chainy (
KUBE-ROUTER-*,KUBE-NWPLCY-*, jedenKUBE-POD-FW-*na pod). Jest częścią binarki i domyślnie włączony. Zapamiętaj go.
Certyfikaty i tokeny
K3s przy pierwszym starcie tworzy własne CA i wszystkie certyfikaty (/var/lib/rancher/k3s/server/tls/), ważne przez rok, i odnawia je automatycznie, gdy usługa startuje w ciągu 90 dni przed wygaśnięciem. Kubeconfig administratora to /etc/rancher/k3s/k3s.yaml; node token w /var/lib/rancher/k3s/server/token to to, czego potrzebowałby drugi węzeł, żeby dołączyć.
🛡️ Dlaczego tu jest
- Semantyka Kubernetesa na jednym małym serwerze. Deploymenty z aktualizacjami rolling lub recreate, probe’y restartujące zawieszony kontener, NetworkPolicies między podami, limity zasobów, admission policy dla obrazów – bez utrzymywania klastra control plane.
- Jedna binarka, jedna unit, jedna przypięta wersja. Całą platformę da się odtworzyć z Ansible; upgrade to „podmień binarkę, zrestartuj unit”.
- Dobre wsparcie dla AlmaLinux i SELinux: utrzymywana polityka SELinux (
k3s-selinux) i containerd z etykietowaniem SELinux.
🔧 Co robi to repozytorium
config.yaml: co jest wyłączone, co włączone
Większość argumentów pochodzi z CIS Kubernetes benchmark: audit log API z rotacją, EventRateLimit, żeby pod w crash loopie nie zalał API eventami, limit PID-ów na pod przeciw fork bombom. Jedna rekomendacja jest celowo pominięta: AlwaysPullImages ściągałoby każdy obraz z registry przy każdym starcie poda – także poda crona WordPressa co pięć minut – i zamieniałoby krótką awarię registry w padające wszędzie pody, w zamian za ochronę multi-tenant, której klaster single-tenant nie potrzebuje.
Przypięty i instalowany w dwóch krokach
Binarka pochodzi z release’u na GitHubie dla k3s_version (versions.yml), skrypt instalacyjny z tego samego taga – nie z get.k3s.io, który zawsze serwuje najnowszy skrypt i w dniu stawiania drugiego serwera Nextcloud przez jakiś czas odpowiadał HTTP 500. Skrypt działa z INSTALL_K3S_SKIP_DOWNLOAD=true, tylko po to, żeby utworzyć unit. Wokół K3s rola instaluje Helm, cert-managera z ClusterIssuerem Let’s Encrypt i kontroler F5 nginx-ingress oraz patchuje każde ServiceAccount default, żeby pody nie dostawały już tokena API, którego nigdy nie używają (CIS 5.1.5). Role aplikacji dodają na każdy namespace ValidatingAdmissionPolicy, która odrzuca pody z obrazami spoza dozwolonej listy registry – wbudowane w API server od Kubernetesa 1.30, bez dodatkowego komponentu.
Ścieżka aktualizacji
- Odczytaj działającą wersję (
k3s --version). - Jeśli różni się od przypiętej: pobierz binarkę przez
get_url,force: true. restoreconna binarce.- Od razu wykonaj handlery – restart dzieje się tutaj, nie na końcu playa.
- Poczekaj, aż
kubectl get nodesodpowie, potem kontynuuj z rolami, które deployują do klastra. - Na końcu runu
common_version_activeporównuje wersję kubeleta zgłaszaną przez API z przypiętą.
Kroki 2, 3 i 6 istnieją każdy z powodu jakiegoś błędu, patrz niżej.
🐛 Sześć rzeczy, których K3s nie zrobił sam
1. Upgrade, który nic nie zrobił
Do 19 października 2026 task pobierania nie miał force. get_url z Ansible pomija wtedy pobieranie, gdy plik docelowy już istnieje – więc każde podbicie wersji od pierwszej instalacji było na istniejących hostach po cichu no-opem. Wyszło to na jaw, bo drift check dla v1.37.1 nie pokazał dla K3s żadnej zmiany. Od tamtej pory smoke test na końcu każdego runu (common_version_active) czyta wersję, którą kubelet faktycznie zgłasza, a nie tę z inventory.
Wniosek: task aktualizacji, który się zakończył, niekoniecznie cokolwiek zaktualizował. Po podbiciu wersji liczy się wersja zgłaszana przez kubeleta.
2. Pody, których SELinux nie ograniczał
SELinux był w trybie enforcing na wszystkich hostach, a katalogi HostPath miały container_file_t. Ale K3s uruchamia containerd z obsługą SELinux tylko wtedy, gdy jego konfiguracja mówi selinux: true – a nie mówiła. Każdy pod działał jako spc_t albo unconfined_service_t, których SELinux w ogóle nie ogranicza. Od 19 października 2026 opcja jest ustawiona, a polityka k3s-selinux zainstalowana; każdy pod działa teraz jako container_t z własnymi kategoriami MCS, a pody istniejące przed przełączeniem trzeba było odtworzyć, żeby to przejęły. Deep dive o SELinux opowiada całą historię.
3. Nowa binarka ze złą etykietą
get_url zapisuje przez plik tymczasowy i zmienia jego nazwę. Nowa binarka dostaje więc etykietę swojego katalogu (bin_t) zamiast container_runtime_exec_t z polityki, i K3s wystartowałby w złej domenie. restorecon po każdym pobraniu to naprawia.
Wniosek: SELinux na hoście nie oznacza SELinux w kontenerze. Runtime musi go jawnie używać, a każda świeżo pobrana binarka potrzebuje potem poprawnej etykiety.
4. Silnik polityk, który nigdy nie był potrzebny
Przez dwa miesiące obok K3s działało Calico jako rzekomy silnik NetworkPolicies. Niczego nie egzekwowało – Felix z Calico obsługuje tylko interfejsy o nazwach cali*, Flannel tworzy veth* – a całe egzekwowanie przez cały czas pochodziło z własnego kontrolera K3s. Dowód był nieprzyjemny: po wyłączeniu kontrolera na potrzeby testu (disable-network-policy) pod w namespace default dosięgnął MariaDB na porcie 3306. Calico zniknęło, a konfiguracja ma teraz komentarz wielkimi literami: nigdy nie wyłączaj wbudowanego kontrolera. Deep dive o nftables opisuje stronę firewalla.
Wniosek: komponent, którego działania nigdy nie przetestowano, to tylko obciążenie – i powód, żeby czuć się bezpiecznie, nie będąc bezpiecznym.
5. Flaga admission, która zastępowała zamiast dodawać
W upstreamowym Kubernetesie --enable-admission-plugins dodaje pluginy do domyślnej listy. W K3s zastępuje własną listę K3s. Ustawienie jej na samo EventRateLimit po cichu wyrzuciło NodeRestriction – plugin, który nie pozwala skompromitowanemu kubeletowi modyfikować obiektów innych węzłów. Wyłapał to ponowny run kube-bench (CIS 1.2.14 przeszło z PASS na FAIL). Teraz oba są wymienione jawnie. Pokrewna pułapka: API server nie tworzy katalogu swojego audit logu i bez niego odmawia startu; rola tworzy go przed restartem.
Wniosek: flaga o tej samej nazwie może w K3s robić coś innego niż w Kubernetesie. Obowiązuje dokumentacja dystrybucji, a nowy run kube-bench po każdej zmianie pokazuje, czy coś się nie zgubiło.
📊 Zmierzone
| Blog | Serwer Nextcloud | |
|---|---|---|
| Wersja K3s | v1.37.1+k3s1 | v1.37.1+k3s1 |
| Pody | 17 | 14 |
Pamięć k3s server (RSS) | 789 MB | 826 MB |
| containerd (RSS) | 202 MB | 190 MB |
Czas CPU k3s server | 23 min w 7,5 h (≈ 5 % rdzenia) | 2,5 h w 9,5 h (≈ 26 % rdzenia) |
| Datastore (state.db + WAL) | 24 + 20 MB | 23 + 20 MB |
| Audit log API przed 20.10.2026 | 1,1 GB (na skonfigurowanym limicie) | 1,0 GB, ~230 MB/dzień |
| Audit log API po zmianie polityki | – | ~28 MB/dzień |
Około gigabajta RAM na cały control plane to cena „prawdziwego Kubernetesa na jednym węźle”. Dwie liczby rzucały się w oczy. Audit log siedział na swoim limicie dziesięciu backupów po 100 MB – rotacja działała, ale „30 dni” z konfiguracji to w rzeczywistości były cztery i pół. A na serwerze Nextcloud control plane zużywał pięć razy więcej CPU niż na blogu, przy mniejszej liczbie podów.
Siedem, to nie bug: ta sama praca za pięciokrotny koszt
Audit log pokazywał to samo obciążenie zapisem na wszystkich trzech serwerach, a 30-sekundowy profil CPU – zrobiony bez restartu przez /debug/pprof kubeleta, który profiluje cały proces K3s – nie wskazywał jednego winowajcy: wszystko było mniej więcej cztery i pół raza droższe, głównie scheduler Go budzący goroutines i stojące za tym wywołania systemowe. Ograniczenie Go do czterech wątków (GOMAXPROCS=4) niczego nie zmieniło. Odpowiedź była w /sys/devices/system/cpu/vulnerabilities/: serwery Nextcloud działają na starszej generacji AMD EPYC, której dotyczy Retbleed, a kernel chroni każdy powrót z funkcji jądra „return thunkiem”. Dla programu, który żyje z wywołań systemowych i przełączeń kontekstu, to dużo kosztuje; nowszy procesor bloga jest „not affected”. Wyłączenie mitygacji na współdzielonej maszynie wirtualnej byłoby lekkomyślne – około 2,6 % ośmiordzeniowego serwera to cena.
Sześć: audit log, który tonął we własnym szumie
Rozbicie jednego pliku 100 MB pokazało, skąd bierze się objętość: heartbeaty leaseów z leader elections i kubeleta (23 %), żądania health, discovery i OpenAPI (14 %), API server rozmawiający sam ze sobą (12 %) oraz żądania tylko do odczytu od własnych komponentów platformy, service accountów i węzłów (około 40 %). Nic z tego nie ma wartości dla bezpieczeństwa; tylko wypychało interesujące wpisy poza okno retencji. Polityka odrzuca teraz dokładnie to – z dwiema regułami celowo umieszczonymi przed regułą odrzucającą: odczyty secretów pozostają logowane dla każdego czytającego, a wszystko, co robi administrator, pozostaje logowane. Symulacja na prawdziwym pliku przewidziała, że zostanie 10 %; po wdrożeniu log rósł o około 28 MB dziennie zamiast 230.
Aktualizacje
Jedna wersja minor naraz, jak wymaga Kubernetes (1.36 → 1.37, nie 1.35 → 1.37). Podbij k3s_version w versions.yml, uruchom drift check (--check --diff) – musi teraz pokazać pobranie binarki –, uruchom playbook i przeczytaj raport wersji na końcu. Restart K3s nie restartuje ani podów, ani kontenerów containerd; API znika na około 20 sekund, strony nie.
Backupy – i co jest naprawdę potrzebne
Datastore celowo nie jest tu backupowany. Każdy obiekt w nim tworzy Ansible z repozytorium i vaulta: namespace’y, Secrety, Deploymenty, polityki. Dane, które się liczą, leżą poza klastrem w katalogach HostPath i w bazach danych, a te każdej nocy ściąga serwer backupów. Odtworzenie serwera oznacza więc: zainstalować AlmaLinux, uruchomić playbook, przywrócić katalogi z danymi. Sam klaster jest jednorazowy – najmocniejszy argument za trzymaniem wszystkiego w kodzie.
🆘 Ściąga: objaw → polecenie
Krótka wersja tego artykułu na chwilę, gdy coś jest nie tak. Uruchamiaj na hoście jako root; <…> to placeholdery.
| Objaw | Polecenie |
|---|---|
| Pod nie startuje | k3s kubectl get pods -Ak3s kubectl -n <ns> describe pod <pod> |
| Dlaczego kontener padł? | k3s kubectl -n <ns> logs <pod> -c <container> --previous |
| Co się ostatnio działo? | k3s kubectl get events -A --sort-by=.lastTimestamp | tail -20 |
| kubectl wisi albo węzeł jest NotReady | systemctl status k3sjournalctl -u k3s --since -15mink3s crictl ps # containerd, without the API server |
| Kto zużywa CPU i pamięć? | k3s kubectl top pods -A |
| Zmieniony ConfigMap lub Secret nieaktywny | k3s kubectl -n <ns> rollout restart deployment/<name> |
| Dysk zapełnia się starymi obrazami | k3s crictl rmi --prune |
| Pod zablokowany przez SELinux? | ausearch -m AVC -ts recent | grep container_tps -eZ | grep container_t | head |
| Kiedy wygasają certyfikaty? | openssl x509 -enddate -noout -in /var/lib/rancher/k3s/server/tls/serving-kube-apiserver.crt |
🎯 Wnioski
- Po aktualizacji sprawdzaj działającą wersję, a nie komunikat taska.
- Kontenery są ograniczone tylko wtedy, gdy runtime używa SELinux;
ps -eZto pokazuje. - Wiedza o flagach Kubernetesa nie przenosi się automatycznie na K3s.
- Audit log potrzebuje polityki, która pomija szum, inaczej szum wypycha wpisy, które się liczą.
- Backupuj tylko to, czego nie da się odtworzyć z repozytorium.
⚖️ Alternatywy – i dlaczego K3s
| Opcja | Mocna strona | Dlaczego nie tutaj |
|---|---|---|
| kubeadm | Upstreamowy Kubernetes, nic ukrytego | etcd, komponenty control plane i CNI musisz sam osobno utrzymywać i aktualizować – dużo jak na jeden węzeł. |
| k0s | Też jedna binarka, czyste ustawienia domyślne | Porównywalny; K3s ma utrzymywaną politykę SELinux i więcej dokumentacji dla AlmaLinux. |
| MicroK8s | Łatwe add-ony | Dystrybuowany jako snap – nie czuje się jak w domu na AlmaLinux. |
| Docker/Podman Compose | Dużo prostsze | Brak probe’ów z restartem, brak NetworkPolicies, brak admission policy, brak rolling updates. |
| K3s | Pełne API Kubernetesa, najmniejszy footprint, polityka SELinux | Wybrany. |
K3s dotrzymuje obietnicy: prawdziwy Kubernetes w jednej binarce. Ostatnie tygodnie pokazały, że „jedna binarka” to także „jedno miejsce, w którym chowają się ustawienia domyślne”. Cztery z sześciu powyższych problemów nie były bugami K3s, tylko ustawieniami domyślnymi i założeniami – SELinux wyłączony, dopóki o niego nie poprosisz, flaga admission, która zastępuje zamiast dodawać, kontroler polityk, który już tam był, i nasza własna reguła audytu łapiąca wszystko, która logowała każdy heartbeat. Każdy z nich jest teraz zapisany jako komentarz w roli, obok linii, która by go przywróciła.
