Deep Dive: K3s – un intero Kubernetes in un solo binario, cosa toglie e sei cose che non ha fatto da solo
Cosa gira nel singolo binario di K3s, cosa questo setup spegne o sostituisce, come si aggiorna un cluster a nodo singolo senza sorprese – e sei default e lacune emersi solo nell'uso reale.

🌐 Anche in: English · Deutsch · Français · Español · Português · Nederlands · Polski
Deep Dive della serie intorno all’Ansible Tour. Il tour spiega i ruoli, i deep dive la tecnologia sottostante: come funziona, perché qui viene usata in questo modo e cosa è andato storto lungo la strada.
K3s è Kubernetes certificato in un singolo binario di circa 70 MB. API server, scheduler, controller manager, kubelet, kube-proxy, containerd, Flannel, CoreDNS e un controller per le network policy partono tutti da un solo processo e da una sola unit systemd. Questo lo rende la scelta ovvia per un cluster di esattamente un nodo – e nasconde parecchio. Questo post spiega cosa gira davvero dentro quel binario, cosa configura la parte 2 del tour e sei cose che K3s non ha fatto da solo, scoperte solo durante l’esercizio.
Indice
🧭 Cosa c’è dentro il binario
Un supervisore, molti componenti
k3s server è un supervisore. Avvia i componenti del control plane di Kubernetes come goroutine dentro il proprio processo – API server, scheduler, controller manager – e accanto a loro i componenti del nodo: il kubelet, kube-proxy, il CNI Flannel e un controller per le network policy integrato (codice da kube-router). containerd gira come processo figlio separato con il proprio socket sotto /run/k3s/containerd/. Tutto condivide un unico flusso di log nel journal (journalctl -u k3s) e un unico numero di versione.
Il datastore: SQLite invece di etcd
Il Kubernetes upstream salva il proprio stato in etcd. Un K3s a nodo singolo usa SQLite tramite kine, uno strato che traduce l’API di etcd in SQL. L’intero stato del cluster – ogni Deployment, Secret, ConfigMap, evento – vive in /var/lib/rancher/k3s/server/db/state.db: 24 MB sul blog, 23 MB su un server Nextcloud, più un write-ahead log da 20 MB. Con più di un nodo server, K3s passa a etcd integrato.
containerd, il CRI e il container pause
Il kubelet parla con containerd tramite la Container Runtime Interface. Per ogni pod, containerd avvia prima un minuscolo container pause che tiene il network namespace del pod; i container veri si uniscono a lui. k3s crictl è il client CRI per guardare direttamente quel livello – pod, container, immagini – senza passare dall’API server. K3s usa cgroup v2 su AlmaLinux 9, quindi i limiti di risorse del pod sono semplici file cgroup sotto /sys/fs/cgroup/kubepods.slice/.
Rete: Flannel, kube-proxy, il controller delle policy
- Flannel dà a ogni pod un indirizzo da
10.42.0.0/16(su un nodo: una/24), crea un bridgecni0e una coppiavethper pod. Backend qui: VXLAN – irrilevante su un nodo, ma il default per un secondo. - kube-proxy trasforma i Service in regole iptables (tramite iptables-nft, in tabelle nftables): DNAT per ClusterIP, NodePort, bilanciamento del carico sugli endpoint.
- Il controller delle network policy trasforma le NetworkPolicy in catene (
KUBE-ROUTER-*,KUBE-NWPLCY-*, unaKUBE-POD-FW-*per pod). Fa parte del binario ed è attivo di default. Ricordatelo.
Certificati e token
K3s crea la propria CA e tutti i certificati al primo avvio (/var/lib/rancher/k3s/server/tls/), validi un anno, e li rinnova automaticamente quando il servizio parte entro 90 giorni dalla scadenza. Il kubeconfig di amministrazione è /etc/rancher/k3s/k3s.yaml; il node token in /var/lib/rancher/k3s/server/token è ciò di cui un secondo nodo avrebbe bisogno per unirsi.
🛡️ Perché è qui
- Semantica di Kubernetes su un piccolo server. Deployment con aggiornamenti rolling o recreate, probe che riavviano un container bloccato, NetworkPolicy tra pod, limiti di risorse, una admission policy per le immagini – senza far girare un cluster di control plane.
- Un binario, una unit, una versione fissata. L’intera piattaforma è riproducibile da Ansible; un upgrade è “sostituisci il binario, riavvia la unit”.
- Buon supporto per AlmaLinux e SELinux: una policy SELinux mantenuta (
k3s-selinux) e containerd con etichettatura SELinux.
🔧 Cosa fa questo repository
config.yaml: cosa viene spento, cosa viene acceso
La maggior parte degli argomenti viene dal CIS Kubernetes benchmark: un audit log dell’API con rotazione, EventRateLimit così un pod in crash loop non può inondare l’API di eventi, un limite di PID per pod contro le fork bomb. Una raccomandazione volutamente non viene seguita: AlwaysPullImages scaricherebbe ogni immagine dal registry a ogni avvio di pod – compreso il pod cron di WordPress ogni cinque minuti – e trasformerebbe un breve disservizio del registry in pod che falliscono ovunque, per una protezione multi-tenant di cui un cluster single-tenant non ha bisogno.
Versione fissata, e installato in due passi
Il binario viene dalla release GitHub di k3s_version (versions.yml), lo script di installazione dallo stesso tag – non da get.k3s.io, che serve sempre lo script più recente e per un po’ ha risposto HTTP 500 proprio il giorno in cui veniva configurato il secondo server Nextcloud. Lo script gira con INSTALL_K3S_SKIP_DOWNLOAD=true, solo per creare la unit. Intorno a K3s il ruolo installa Helm, cert-manager con un ClusterIssuer Let’s Encrypt e l’ingress controller F5 nginx-ingress, e modifica ogni ServiceAccount default in modo che i pod non ricevano più un token API che non usano mai (CIS 5.1.5). I ruoli applicativi aggiungono per ogni namespace una ValidatingAdmissionPolicy che rifiuta i pod le cui immagini non provengono da un elenco consentito di registry – integrata nell’API server da Kubernetes 1.30, nessun componente aggiuntivo.
Il percorso di upgrade
- Leggere la versione in esecuzione (
k3s --version). - Se differisce da quella fissata: scaricare il binario con
get_url,force: true. restoreconsul binario.- Eseguire subito gli handler – il riavvio avviene qui, non alla fine del play.
- Aspettare che
kubectl get nodesrisponda, poi continuare con i ruoli che fanno deploy nel cluster. - Alla fine dell’esecuzione,
common_version_activeconfronta la versione del kubelet riportata dall’API con quella fissata.
I passi 2, 3 e 6 esistono ciascuno per via di un errore, vedi sotto.
🐛 Sei cose che K3s non ha fatto da solo
1. L’upgrade che non faceva niente
Fino al 19 ottobre 2026 il task di download non aveva force. get_url di Ansible salta il download quando il file di destinazione esiste già – quindi ogni aumento di versione dalla prima installazione era stato, in silenzio, un no-op sugli host esistenti. È venuto fuori perché il drift check per la v1.37.1 non mostrava alcuna modifica per K3s. Da allora lo smoke test alla fine di ogni esecuzione (common_version_active) legge la versione che il kubelet riporta davvero, non quella nell’inventory.
Il succo: un task di aggiornamento che termina non ha necessariamente aggiornato qualcosa. Dopo un aumento di versione conta la versione che riporta il kubelet.
2. Pod che SELinux non confinava
SELinux era in enforcing su tutti gli host e le directory HostPath avevano container_file_t. Ma K3s avvia containerd con il supporto SELinux solo quando la sua configurazione dice selinux: true – e non lo diceva. Ogni pod girava come spc_t o unconfined_service_t, che SELinux non limita affatto. Dal 19 ottobre 2026 l’opzione è impostata e la policy k3s-selinux è installata; ogni pod ora gira come container_t con le proprie categorie MCS, e i pod che esistevano prima del cambio hanno dovuto essere ricreati per adottarlo. Il deep dive su SELinux racconta tutta la storia.
3. Un nuovo binario con l’etichetta sbagliata
get_url scrive tramite un file temporaneo e poi lo rinomina. Il nuovo binario riceve quindi l’etichetta della sua directory (bin_t) invece di container_runtime_exec_t dalla policy, e K3s partirebbe nel dominio sbagliato. Un restorecon dopo ogni download lo sistema.
Il succo: SELinux sull’host non significa SELinux nel container. Il runtime deve usarlo esplicitamente, e ogni binario appena scaricato ha bisogno della sua etichetta corretta dopo.
4. Il motore di policy che non serviva mai
Per due mesi Calico è girato accanto a K3s come presunto motore delle NetworkPolicy. Non imponeva niente – Felix di Calico gestisce solo interfacce chiamate cali*, Flannel crea veth* – e tutta l’applicazione delle regole era venuta per tutto il tempo dal controller di K3s stesso. La prova è stata spiacevole: con il controller spento per un test (disable-network-policy), un pod nel namespace default raggiungeva MariaDB sulla porta 3306. Calico non c’è più, e la configurazione ora porta un commento in maiuscolo: non disattivare mai il controller integrato. Il deep dive su nftables descrive il lato firewall.
Il succo: un componente il cui effetto non è mai stato testato è solo carico – e un motivo per sentirsi al sicuro senza esserlo.
5. Un flag di admission che sostituiva invece di aggiungere
Nel Kubernetes upstream, --enable-admission-plugins aggiunge plugin alla lista di default. In K3s sostituisce la lista di K3s stesso. Impostarlo solo su EventRateLimit ha eliminato in silenzio NodeRestriction – il plugin che impedisce a un kubelet compromesso di modificare gli oggetti di altri nodi. Una nuova esecuzione di kube-bench l’ha scoperto (CIS 1.2.14 è passato da PASS a FAIL). Ora sono elencati entrambi esplicitamente. Una trappola collegata: l’API server non crea la directory del suo audit log e si rifiuta di partire senza; il ruolo la crea prima del riavvio.
Il succo: un flag con lo stesso nome può fare in K3s qualcosa di diverso che in Kubernetes. Vale la documentazione della distribuzione, e una nuova esecuzione di kube-bench dopo ogni modifica mostra se si è perso qualcosa.
📊 Misurato
| Blog | Server Nextcloud | |
|---|---|---|
| Versione K3s | v1.37.1+k3s1 | v1.37.1+k3s1 |
| Pod | 17 | 14 |
Memoria di k3s server (RSS) | 789 MB | 826 MB |
| containerd (RSS) | 202 MB | 190 MB |
Tempo CPU di k3s server | 23 min in 7,5 h (≈ 5 % di un core) | 2,5 h in 9,5 h (≈ 26 % di un core) |
| Datastore (state.db + WAL) | 24 + 20 MB | 23 + 20 MB |
| Audit log dell’API prima del 20 ott 2026 | 1,1 GB (al limite configurato) | 1,0 GB, ~230 MB/giorno |
| Audit log dell’API dopo il cambio di policy | – | ~28 MB/giorno |
Circa un gigabyte di RAM per l’intero control plane è il prezzo di “Kubernetes vero su un nodo”. Due numeri saltavano all’occhio. L’audit log stava al suo limite di dieci backup da 100 MB – la rotazione funzionava, ma i “30 giorni” della configurazione erano in realtà quattro e mezzo. E sul server Nextcloud il control plane usava cinque volte la CPU del blog, con meno pod.
Sette, non un bug: lo stesso lavoro a cinque volte il costo
L’audit log mostrava lo stesso carico di scrittura su tutti e tre i server, e un profilo CPU di 30 secondi – preso senza riavvio tramite /debug/pprof del kubelet, che profila l’intero processo K3s – non mostrava un singolo colpevole: tutto costava circa quattro volte e mezzo tanto, soprattutto lo scheduler di Go che sveglia goroutine e le chiamate di sistema dietro. Limitare Go a quattro thread (GOMAXPROCS=4) non ha cambiato niente. La risposta era in /sys/devices/system/cpu/vulnerabilities/: i server Nextcloud girano su una generazione più vecchia di AMD EPYC colpita da Retbleed, e il kernel protegge ogni ritorno da una funzione del kernel con un “return thunk”. Per un programma che vive di chiamate di sistema e cambi di contesto costa molto; la CPU più nuova del blog è “not affected”. Spegnere la mitigazione su una macchina virtuale condivisa sarebbe imprudente – circa il 2,6 % di un server a otto core è il prezzo.
Sei: un audit log annegato nel proprio rumore
Una scomposizione di un file da 100 MB ha mostrato da dove veniva il volume: heartbeat dei lease delle leader election e del kubelet (23 %), richieste di health, discovery e OpenAPI (14 %), l’API server che parla con se stesso (12 %) e richieste in sola lettura dei componenti della piattaforma, dei service account e dei nodi (circa 40 %). Niente di tutto ciò ha valore per la sicurezza; spingeva solo le voci interessanti fuori dalla finestra di conservazione. La policy ora scarta esattamente queste – con due regole messe di proposito prima della regola di scarto: le letture dei secret restano registrate per ogni lettore, e tutto ciò che fa un amministratore resta registrato. Una simulazione sul file reale prevedeva che ne sarebbe rimasto il 10 %; dopo il rollout il log cresceva di circa 28 MB al giorno invece di 230.
Upgrade
Una versione minor alla volta, come richiede Kubernetes (1.36 → 1.37, non 1.35 → 1.37). Alzare k3s_version in versions.yml, eseguire il drift check (--check --diff) – ora deve mostrare il download del binario –, eseguire il playbook e leggere il report delle versioni alla fine. Un riavvio di K3s non riavvia né i pod né i container di containerd; l’API sparisce per circa 20 secondi, i siti web no.
Backup – e cosa serve davvero
Il datastore qui non viene salvato, di proposito. Ogni oggetto al suo interno viene creato da Ansible a partire dal repository e dal vault: namespace, Secret, Deployment, policy. I dati che contano vivono fuori dal cluster in directory HostPath e nei database, e quelli vengono prelevati ogni notte dal server di backup. Ripristinare un server significa quindi: installare AlmaLinux, eseguire il playbook, ripristinare le directory dei dati. Il cluster stesso è usa e getta – l’argomento più forte per tenere tutto nel codice.
🆘 Cheat sheet: sintomo → comando
La versione breve di questo articolo per il momento in cui qualcosa non va. Da eseguire sull’host come root; <…> sono segnaposto.
| Sintomo | Comando |
|---|---|
| Un pod non parte | k3s kubectl get pods -Ak3s kubectl -n <ns> describe pod <pod> |
| Perché è crashato un container? | k3s kubectl -n <ns> logs <pod> -c <container> --previous |
| Cos’è successo di recente? | k3s kubectl get events -A --sort-by=.lastTimestamp | tail -20 |
| kubectl si blocca o il nodo è NotReady | systemctl status k3sjournalctl -u k3s --since -15mink3s crictl ps # containerd, without the API server |
| Chi usa CPU e memoria? | k3s kubectl top pods -A |
| ConfigMap o Secret modificato non attivo | k3s kubectl -n <ns> rollout restart deployment/<name> |
| Disco che si riempie di vecchie immagini | k3s crictl rmi --prune |
| Pod bloccato da SELinux? | ausearch -m AVC -ts recent | grep container_tps -eZ | grep container_t | head |
| Quando scadono i certificati? | openssl x509 -enddate -noout -in /var/lib/rancher/k3s/server/tls/serving-kube-apiserver.crt |
🎯 Le lezioni
- Dopo un aggiornamento controlla la versione in esecuzione, non il messaggio del task.
- I container sono confinati solo se il runtime usa SELinux;
ps -eZlo mostra. - Le conoscenze sui flag di Kubernetes non valgono automaticamente per K3s.
- Un audit log ha bisogno di una policy che lasci fuori il rumore, altrimenti il rumore spinge fuori le voci che contano.
- Fai il backup solo di ciò che non si può ricreare dal repository.
⚖️ Alternative – e perché K3s
| Opzione | Punto di forza | Perché non qui |
|---|---|---|
| kubeadm | Kubernetes upstream, niente di nascosto | etcd, i componenti del control plane e il CNI li devi gestire e aggiornare tu separatamente – tanto per un nodo. |
| k0s | Anche lui un singolo binario, default puliti | Paragonabile; K3s ha la policy SELinux mantenuta e più documentazione per AlmaLinux. |
| MicroK8s | Add-on facili | Distribuito come snap – non a casa sua su AlmaLinux. |
| Docker/Podman Compose | Molto più semplice | Niente probe con riavvio, niente NetworkPolicy, niente admission policy, niente rolling update. |
| K3s | API Kubernetes completa, ingombro minimo, policy SELinux | Scelto. |
K3s mantiene la sua promessa: Kubernetes vero in un solo binario. Quello che hanno mostrato le ultime settimane è che “un solo binario” è anche “un solo posto dove si nascondono i default”. Quattro dei sei problemi qui sopra non erano bug di K3s ma default e supposizioni – SELinux spento se non lo chiedi, un flag di admission che sostituisce invece di aggiungere, un controller delle policy che c’era già, e la nostra regola di audit pigliatutto che registrava ogni heartbeat. Ognuno di essi ora è scritto come commento nel ruolo, accanto alla riga che lo riporterebbe indietro.
