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.

Ilustracja do serii Deep Dive

🌐 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 bridge cni0 i parę veth na 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-*, jeden KUBE-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

  1. Odczytaj działającą wersję (k3s --version).
  2. Jeśli różni się od przypiętej: pobierz binarkę przez get_url, force: true.
  3. restorecon na binarce.
  4. Od razu wykonaj handlery – restart dzieje się tutaj, nie na końcu playa.
  5. Poczekaj, aż kubectl get nodes odpowie, potem kontynuuj z rolami, które deployują do klastra.
  6. Na końcu runu common_version_active poró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

BlogSerwer Nextcloud
Wersja K3sv1.37.1+k3s1v1.37.1+k3s1
Pody1714
Pamięć k3s server (RSS)789 MB826 MB
containerd (RSS)202 MB190 MB
Czas CPU k3s server23 min w 7,5 h (≈ 5 % rdzenia)2,5 h w 9,5 h (≈ 26 % rdzenia)
Datastore (state.db + WAL)24 + 20 MB23 + 20 MB
Audit log API przed 20.10.20261,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.

ObjawPolecenie
Pod nie startujek3s kubectl get pods -A
k3s 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 NotReadysystemctl status k3s
journalctl -u k3s --since -15min
k3s crictl ps # containerd, without the API server
Kto zużywa CPU i pamięć?k3s kubectl top pods -A
Zmieniony ConfigMap lub Secret nieaktywnyk3s kubectl -n <ns> rollout restart deployment/<name>
Dysk zapełnia się starymi obrazamik3s crictl rmi --prune
Pod zablokowany przez SELinux?ausearch -m AVC -ts recent | grep container_t
ps -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 -eZ to 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

OpcjaMocna stronaDlaczego nie tutaj
kubeadmUpstreamowy Kubernetes, nic ukrytegoetcd, komponenty control plane i CNI musisz sam osobno utrzymywać i aktualizować – dużo jak na jeden węzeł.
k0sTeż jedna binarka, czyste ustawienia domyślnePorównywalny; K3s ma utrzymywaną politykę SELinux i więcej dokumentacji dla AlmaLinux.
MicroK8sŁatwe add-onyDystrybuowany jako snap – nie czuje się jak w domu na AlmaLinux.
Docker/Podman ComposeDużo prostszeBrak probe’ów z restartem, brak NetworkPolicies, brak admission policy, brak rolling updates.
K3sPełne API Kubernetesa, najmniejszy footprint, polityka SELinuxWybrany.

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.

Część tekstów i obrazów na tej stronie powstała z pomocą AI lub została wygenerowana przez AI. Szczegóły