k3s

Sezione · Informatica

k3s

k3s è una distribuzione Kubernetes leggera: un solo binario, pochi requisiti e un'installazione che sta in una riga. La guida copre architettura, installazione, comandi, datastore, rete, storage e sicurezza, con particolare attenzione ai default e ai percorsi reali.

Versione documentata: k3s v1.37.2+k3s1 (3 novembre 2026), che aggiorna Kubernetes a v1.37.2. Licenza Apache 2.0; documentazione CC BY 4.0. Include containerd 2.3.7, Traefik 3.7.14, Flannel 0.28.10 e Gateway API 1.6.3. Per le risorse Kubernetes di base resta disponibile la guida Kubernetes.

Che cos'è k3s

k3s è una distribuzione Kubernetes leggera e autosufficiente, distribuita come un singolo binario da meno di 100 MB. Raccoglie in un unico eseguibile il control plane, il kubelet, il runtime dei container e i componenti di rete che di solito si installano separatamente. È un progetto CNCF Sandbox dal 19 agosto 2020, con codice Apache 2.0.

L'obiettivo non è sostituire un cluster Kubernetes completo, ma rendere Kubernetes utilizzabile dove un'installazione tradizionale sarebbe sproporzionata: server piccoli, ambienti edge, dispositivi IoT, laboratori, CI/CD e macchine con poca RAM. Le API restano quelle di Kubernetes, quindi manifest, Helm chart, kubectl e operatori funzionano come al solito.

Architettura k3s con un server e database SQLite incorporato, collegato a due agent
Cluster a server singolo con database SQLite incorporato. Fonte: k3s Docs — Architecture, licenza CC BY 4.0. · Apri a dimensione intera.

Server e agent

k3s usa due ruoli. Un server esegue il control plane e il datastore; un agent esegue solo il kubelet, il runtime e la rete. Entrambi avviano kubelet, containerd e la CNI. Per semplicità, un server esegue anche i componenti dell'agent ed è programmabile per i workload per default.

RuoloCosa esegueQuando serve
k3s server API server, scheduler, controller-manager, cloud-controller-manager, datastore e componenti agent. Almeno un nodo; per l'alta disponibilità tre o più server.
k3s agent containerd, Flannel, kubelet, kube-proxy e controller delle network policy. Nodi aggiuntivi che eseguono solo i carichi di lavoro.

Alta disponibilità

Per un control plane ridondante servono tre o più server, sempre in numero dispari quando il datastore è etcd incorporato: il quorum si calcola come (n/2)+1. Il primo server si inizializza con --cluster-init; gli altri si uniscono con --server https://server1:6443. In alternativa si può usare un database esterno.

Architettura k3s ad alta disponibilità con tre server e etcd incorporato, un load balancer e due agent
Alta disponibilità con etcd incorporato e indirizzo di registrazione fisso. Fonte: k3s Docs — Architecture, licenza CC BY 4.0. · Apri a dimensione intera.

Datastore

La scelta del datastore dipende dal numero di server e dai requisiti di disponibilità. k3s seleziona automaticamente etcd se trova un cluster da inizializzare o un database etcd già presente su disco; altrimenti usa SQLite.

DatastoreServerNote
SQLite Uno Default. Semplice e senza dipendenze, ma non può essere condiviso da più server.
etcd incorporato Tre o più, dispari Scelta tipica per l'HA senza gestire un database esterno. Richiede dischi veloci.
MySQL / MariaDB Due o più Database esterno gestito fuori da k3s. MySQL 8.0/8.4; MariaDB 10.11/11.4.
PostgreSQL Due o più Database esterno. Versioni certificate: 15.12, 16.7 e 17.3.
etcd esterno Due o più Per chi gestisce già un cluster etcd. Certificato contro etcd 3.5.21.

Componenti inclusi

k3s non è solo Kubernetes: include anche i pezzi che di solito si installano a parte. Quasi tutti sono AddOn gestiti tramite i manifest in /var/lib/rancher/k3s/server/manifests.

ComponenteRuoloCome si disabilita
containerdRuntime dei container.Si può usare cri-dockerd con --docker, opzione sperimentale.
FlannelCNI predefinita, con backend VXLAN.--flannel-backend=none per usare una CNI propria.
CoreDNSDNS interno del cluster.--disable=coredns.
TraefikIngress controller e reverse proxy.--disable=traefik.
ServiceLBController LoadBalancer basato su hostPort.--disable=servicelb.
kube-router netpolApplica le NetworkPolicy.--disable-network-policy.
local-path-provisionerStorageClass local-path per volumi locali.--disable=local-storage.
metrics-serverMetriche di pod e nodi per kubectl top.--disable=metrics-server.
Helm controllerInstalla Helm chart tramite manifest e HelmChartConfig.--disable-helm-controller.

Quando sceglierlo

Buon fitMeno adatto
Server con 2 core e 2 GB di RAM, Raspberry Pi, mini PC, device edge. Cluster con molti server e carichi che richiedono un control plane molto personalizzato.
Laboratori, demo, ambienti di test e CI/CD che devono partire in fretta. Requisiti di alta disponibilità senza dischi veloci per etcd.
Installazioni air-gap o con connettività intermittente. Ambienti che richiedono Windows nativo: k3s non lo supporta.
Chi vuole le API Kubernetes senza montare e mantenere ogni componente a mano. Chi ha già una piattaforma Kubernetes gestita e non ha bisogno di un cluster locale.

Requisiti minimi

I requisiti riguardano k3s e i suoi componenti, non i workload. Le prestazioni dipendono molto dal disco: per etcd è consigliato un SSD, non una scheda SD o eMMC.

NodoCPURAM
Server2 core2 GB
Agent1 core512 MB

Per il dimensionamento del control plane, la guida ufficiale indica circa 0-350 agent con 2 core e 4 GB, 351-900 con 4 core e 8 GB, 901-1800 con 8 core e 16 GB e oltre 1800 con 16+ core e 32 GB. Con tre server in HA si può scalare di circa il 50% in più; gli agent conviene aggiungerli in gruppi da 50 o meno.

  • Linux moderno, kernel con supporto a cgroup; architetture x86_64, armhf e arm64/aarch64.
  • Hostname univoci. Se vengono riutilizzati, usare --with-node-id o --node-name.
  • Firewall: aprire le porte necessarie o disabilitare firewalld/ufw.
  • Su Raspberry Pi OS abilitare i cgroup in /boot/firmware/cmdline.txt.
  • Su RHEL 10 installare kernel-modules-extra.

Porte

PortaProtocolloUso
6443TCPAPI Kubernetes e supervisor k3s; deve essere raggiungibile da tutti i nodi.
8472UDPFlannel VXLAN. Non esporla a Internet.
51820UDPFlannel WireGuard con IPv4.
51821UDPFlannel WireGuard con IPv6.
10250TCPKubelet: metriche e API; serve al metrics-server.
2379-2380TCPSolo per l'HA con etcd incorporato, tra i server.

Fonti