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.
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.
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.
| Ruolo | Cosa esegue | Quando 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.
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.
| Datastore | Server | Note |
|---|---|---|
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.
| Componente | Ruolo | Come si disabilita |
|---|---|---|
containerd | Runtime dei container. | Si può usare cri-dockerd con --docker, opzione sperimentale. |
Flannel | CNI predefinita, con backend VXLAN. | --flannel-backend=none per usare una CNI propria. |
CoreDNS | DNS interno del cluster. | --disable=coredns. |
Traefik | Ingress controller e reverse proxy. | --disable=traefik. |
ServiceLB | Controller LoadBalancer basato su hostPort. | --disable=servicelb. |
kube-router netpol | Applica le NetworkPolicy. | --disable-network-policy. |
local-path-provisioner | StorageClass local-path per volumi locali. | --disable=local-storage. |
metrics-server | Metriche di pod e nodi per kubectl top. | --disable=metrics-server. |
Helm controller | Installa Helm chart tramite manifest e HelmChartConfig. | --disable-helm-controller. |
Quando sceglierlo
| Buon fit | Meno 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.
| Nodo | CPU | RAM |
|---|---|---|
| Server | 2 core | 2 GB |
| Agent | 1 core | 512 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,armhfearm64/aarch64. - Hostname univoci. Se vengono riutilizzati, usare
--with-node-ido--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
| Porta | Protocollo | Uso |
|---|---|---|
6443 | TCP | API Kubernetes e supervisor k3s; deve essere raggiungibile da tutti i nodi. |
8472 | UDP | Flannel VXLAN. Non esporla a Internet. |
51820 | UDP | Flannel WireGuard con IPv4. |
51821 | UDP | Flannel WireGuard con IPv6. |
10250 | TCP | Kubelet: metriche e API; serve al metrics-server. |
2379-2380 | TCP | Solo per l'HA con etcd incorporato, tra i server. |
Fonti
Prima di iniziare
Servono un host Linux con hostname univoco, i cgroup attivi e le porte libere. Lo script ufficiale installa k3s come servizio systemd o OpenRC; su sistemi senza questi init system si può usare il binario o il container.
uname -m
cat /etc/os-release
systemctl status firewalld
ufw status
curl -sfL https://get.k3s.io | sh -s - --help
L'ultimo comando non installa nulla: scarica lo script e mostra le
opzioni disponibili. Dopo l'installazione, k3s check-config
controlla i prerequisiti del sistema.
Installazione rapida del server
Con i default si ottiene un server con SQLite, Flannel, CoreDNS, Traefik, ServiceLB, local-path, metrics-server e Helm controller:
curl -sfL https://get.k3s.io | sh -
Al termine l'installer ha creato:
- il binario
/usr/local/bin/k3se il serviziok3s; - il kubeconfig
/etc/rancher/k3s/k3s.yaml, di proprietà di root e con mode600; - il token del server in
/var/lib/rancher/k3s/server/token; - i dati in
/var/lib/rancher/k3se i manifest degli AddOn in/var/lib/rancher/k3s/server/manifests; - gli script
k3s-uninstall.shek3s-killall.shin/usr/local/bin.
Verifica
sudo systemctl status k3s
sudo journalctl -u k3s -f
sudo k3s kubectl get nodes -o wide
sudo k3s kubectl get pods -A
sudo k3s kubectl cluster-info
Il nodo deve risultare Ready. I pod di sistema girano
nel namespace kube-system: CoreDNS, Traefik,
local-path-provisioner, metrics-server e gli altri AddOn.
Kubeconfig per l'utente
k3s kubectl usa automaticamente
/etc/rancher/k3s/k3s.yaml se KUBECONFIG
non è impostata. Per usare il kubectl di sistema
si può esportare la variabile o copiare il file:
export KUBECONFIG=/etc/rancher/k3s/k3s.yaml
mkdir -p ~/.kube
sudo cp /etc/rancher/k3s/k3s.yaml ~/.kube/config
sudo chown $(id -u):$(id -g) ~/.kube/config
chmod 600 ~/.kube/config
Se il server è remoto, nel kubeconfig il campo
server va cambiato da 127.0.0.1
all'indirizzo raggiungibile del server.
Aggiungere un agent
Recuperare il token dal server e usarlo sul nodo da aggiungere. La
presenza di K3S_URL fa assumere il ruolo di agent:
sudo cat /var/lib/rancher/k3s/server/token
curl -sfL https://get.k3s.io | K3S_URL=https://10.0.0.11:6443 K3S_TOKEN=K10SECRET sh -
Il token del server dà accesso amministrativo al cluster: va
trattato come una password. Per gli agent si può configurare un
token separato con --agent-token; se non lo si fa, il
token dell'agent è lo stesso del server.
Configurazione con file YAML
Il file predefinito è /etc/rancher/k3s/config.yaml;
i drop-in stanno in /etc/rancher/k3s/config.yaml.d/*.yaml
e vengono letti in ordine alfabetico. I flag da riga di comando hanno
la precedenza sul file.
write-kubeconfig-mode: "0644"
tls-san:
- "k3s.example.com"
node-label:
- "ambiente=produzione"
disable:
- traefik
secrets-encryption: true
cluster-init: true
I nomi delle chiavi corrispondono ai flag senza i due trattini; i
flag ripetibili diventano liste. Nei drop-in, il suffisso +
aggiunge un valore invece di sostituirlo:
node-taint+:
- "dedicato=infra:NoSchedule"
config.yaml non viene gestito dall'installer: per una
configurazione stabile conviene usare il file YAML.
HA con etcd incorporato
Il primo server inizializza il cluster; gli altri si uniscono
passando l'indirizzo del primo. Servono almeno tre server e un
indirizzo di registrazione fisso, per esempio un load balancer, da
indicare in --tls-san.
curl -sfL https://get.k3s.io | K3S_TOKEN=SECRET sh -s - server --cluster-init --tls-san=203.0.113.10
curl -sfL https://get.k3s.io | K3S_TOKEN=SECRET sh -s - server --server https://10.0.0.11:6443 --tls-san=203.0.113.10
Aggiungere gli agent con lo stesso token e K3S_URL
puntato all'indirizzo fisso. Dopo il join, ogni server mostra i ruoli
control-plane,etcd,master.
HA con database esterno
In alternativa a etcd incorporato si può usare MySQL,
MariaDB, PostgreSQL o etcd esterno. L'endpoint si passa con
--datastore-endpoint o K3S_DATASTORE_ENDPOINT:
curl -sfL https://get.k3s.io | K3S_TOKEN=SECRET sh -s - server --datastore-endpoint="postgres://k3s:password@db.example.com:5432/k3s"
Il database deve essere raggiungibile da tutti i server e va configurato per i backup secondo le procedure del DBMS. k3s richiede il supporto alle prepared statement.
Disabilitare componenti
Gli AddOn si disattivano con --disable; la disattivazione
elimina anche il manifest corrispondente. Esempio con Traefik e
ServiceLB:
curl -sfL https://get.k3s.io | sh -s - server --disable=traefik,servicelb
--cluster-cidr, --service-cidr,
--cluster-dns, --cluster-domain,
--disable=servicelb, --secrets-encryption e
simili, i nuovi server non riescono a unirsi o il cluster si
comporta in modo incoerente.
Installazione air-gap
In un ambiente senza Internet servono il binario, lo script di
installazione e le immagini dei componenti. Le immagini vanno messe
in /var/lib/rancher/k3s/agent/images/ su ogni nodo;
poi si installa con INSTALL_K3S_SKIP_DOWNLOAD=true.
sudo mkdir -p /var/lib/rancher/k3s/agent/images/
sudo cp k3s-airgap-images-amd64.tar.zst /var/lib/rancher/k3s/agent/images/
chmod +x install.sh
INSTALL_K3S_SKIP_DOWNLOAD=true ./install.sh
Per un agent air-gap si aggiungono K3S_URL e
K3S_TOKEN. In alternativa si può usare un registry
privato o il registry distribuito incorporato.
Disinstallazione
Gli script vengono creati dall'installer. Attenzione: la disinstallazione elimina il datastore locale, i volumi locali e la configurazione del nodo.
sudo /usr/local/bin/k3s-uninstall.sh
sudo /usr/local/bin/k3s-agent-uninstall.sh
Fonti
Digita per filtrare le tabelle e i comandi qui sotto.
Servizio e log
Dopo l'installazione con lo script, k3s gira come servizio. Fermare
il servizio non ferma i container dei pod: per quello serve
k3s-killall.sh.
| Comando | Cosa fa | Note |
|---|---|---|
sudo systemctl status k3s | Stato del server | Per gli agent: k3s-agent. |
sudo systemctl restart k3s | Riavvia il server | I pod continuano a girare. |
sudo systemctl stop k3s | Ferma il servizio | Non elimina i dati. |
sudo journalctl -u k3s -f | Segue i log del server | Per gli agent: -u k3s-agent. |
sudo /usr/local/bin/k3s-killall.sh | Ferma container e resetta lo stato | Pulisce anche rete e regole iptables; i dati del cluster restano. |
sudo rc-service k3s restart | Riavvio su OpenRC | Alternativa a systemd. |
Cluster, nodi e workload
| Comando | Cosa fa | Note |
|---|---|---|
sudo k3s kubectl get nodes -o wide | Elenca i nodi | Mostra IP, versione e runtime. |
sudo k3s kubectl get pods -A | Pod di tutti i namespace | Utile per controllare gli AddOn. |
sudo k3s kubectl cluster-info | Endpoint del control plane | Verifica rapida della API. |
sudo k3s kubectl top nodes | Metriche dei nodi | Richiede metrics-server. |
sudo k3s kubectl describe node <NOME> | Dettaglio del nodo | Eventi, taint, allocazione. |
sudo k3s kubectl drain <NOME> --ignore-daemonsets | Svuota un nodo | Prima di manutenzione o upgrade. |
sudo k3s kubectl uncordon <NOME> | Rimette il nodo in servizio | Dopo la manutenzione. |
sudo k3s kubectl get events -A --sort-by=.lastTimestamp | Eventi recenti | Per capire cosa non parte. |
Strumenti inclusi nel binario
k3s incorpora kubectl, crictl
e ctr. Sono utili per la diagnostica e per non dover
installare client separati sul nodo.
sudo k3s kubectl get pods
sudo k3s crictl ps
sudo k3s crictl images
sudo k3s ctr containers list
sudo k3s ctr images list
crictl parla con il runtime tramite CRI; ctr
è il client nativo di containerd. Per un uso quotidiano
kubectl è quasi sempre la scelta giusta.
Snapshot etcd
Con etcd incorporato i backup si gestiscono con
k3s etcd-snapshot. Gli snapshot programmati sono attivi
per default ogni 12 ore (0 */12 * * *), con retention 5
e directory /var/lib/rancher/k3s/server/db/snapshots.
Gli snapshot on-demand non hanno retention automatica.
| Comando | Cosa fa | Note |
|---|---|---|
sudo k3s etcd-snapshot save | Crea uno snapshot on-demand | Nome base on-demand. |
sudo k3s etcd-snapshot save --name pre-upgrade | Snapshot con nome riconoscibile | Comodo prima di un upgrade. |
sudo k3s etcd-snapshot ls | Elenca gli snapshot | Alias: list, l. |
sudo k3s etcd-snapshot delete <NOME> | Elimina uno snapshot | Accetta più nomi. |
sudo k3s etcd-snapshot prune --snapshot-retention 3 | Riduce gli snapshot on-demand | La retention è obbligatoria per gli on-demand. |
sudo k3s etcd-snapshot save --etcd-snapshot-compress | Salva comprimendo | Utile per risparmiare spazio. |
sudo k3s etcd-snapshot save --name pre-upgrade
sudo k3s etcd-snapshot ls
sudo k3s etcd-snapshot prune --snapshot-retention 3
Per copiare gli snapshot su S3 si usano i flag --etcd-s3,
--etcd-s3-bucket, --etcd-s3-region e le
credenziali corrispondenti. La retention S3 si controlla con
--etcd-s3-retention.
Ripristino
Il ripristino richiede il token originale: gli snapshot sono cifrati con una chiave derivata dal token del server. Senza quel token lo snapshot è inutilizzabile.
sudo systemctl stop k3s
sudo k3s server --cluster-reset --cluster-reset-restore-path=/var/lib/rancher/k3s/server/db/snapshots/<NOME>
sudo systemctl start k3s
In un cluster HA si fermano tutti i server, si esegue il restore su
un solo server, si eliminano i dati /var/lib/rancher/k3s/server/db/
sugli altri e si riavviano. Se si ripristina su host nuovi, passare
il token originale con --token.
Token
Il token del server abilita il join e cifra i dati riservati nel
datastore. I token bootstrap, invece, sono temporanei e si gestiscono
con k3s token.
| Comando | Cosa fa | Note |
|---|---|---|
sudo k3s token list | Elenca i token bootstrap | Mostra ID, descrizione e TTL residuo. |
sudo k3s token create --ttl 1h | Crea un token temporaneo | Il segreto viene mostrato una sola volta. |
sudo k3s token delete <ID> | Elimina un token | Accetta anche il token completo. |
sudo k3s token rotate | Ruota il token del server | Dopo la rotazione vanno riavviati server e agent. |
sudo cat /var/lib/rancher/k3s/server/token
sudo k3s token list
sudo k3s token create --ttl 1h --description "join temporaneo"
Secrets encryption
L'attivazione va fatta all'avvio del server con
--secrets-encryption. Lo stato e la rotazione delle
chiavi si gestiscono con k3s secrets-encrypt.
| Comando | Cosa fa | Note |
|---|---|---|
sudo k3s secrets-encrypt status | Stato della cifratura | Mostra anche la fase di rotazione. |
sudo k3s secrets-encrypt enable | Abilita su un cluster esistente | Richiede riavvio e poi rotate-keys. |
sudo k3s secrets-encrypt disable | Disabilita | Richiede riavvio e reencrypt. |
sudo k3s secrets-encrypt rotate-keys | Ruota le chiavi | La reencrypt procede a circa 5 secret al secondo. |
sudo k3s secrets-encrypt reencrypt | Riscrive i secret esistenti | Utile dopo un cambio di chiave. |
sudo k3s secrets-encrypt status
sudo k3s secrets-encrypt rotate-keys
reencrypt_finished e riavviare i
server nell'ordine indicato.
Certificati
I certificati foglia valgono 365 giorni e vengono rinnovati automaticamente quando ne mancano 120. Le CA durano 10 anni e non si rinnovano da sole.
sudo k3s certificate check --output table
sudo systemctl stop k3s
sudo k3s certificate rotate
sudo systemctl start k3s
Per ruotare solo alcuni certificati si usa
--service <NOME>. La rotazione delle CA si fa con
k3s certificate rotate-ca, seguendo la procedura
dedicata.
Aggiornamento
Si aggiornano prima i server, uno alla volta, poi gli agent. Lo script va rieseguito con le stesse variabili e gli stessi argomenti dell'installazione originale. Rispettare il version skew di Kubernetes: non si saltano minor.
curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION=v1.37.2+k3s1 sh -
curl -sfL https://get.k3s.io | INSTALL_K3S_CHANNEL=stable sh -
curl -sfL https://get.k3s.io | INSTALL_K3S_SKIP_START=true sh -
Prima di un upgrade si può creare uno snapshot con
k3s etcd-snapshot save --name pre-upgrade e, se il
carico è sensibile alle brevi interruzioni dell'API, svuotare
il nodo con kubectl drain.
Fonti
Rete
La CNI predefinita è Flannel in modalità VXLAN. k3s assegna ai pod e ai servizi due intervalli distinti e configura CoreDNS sul primo indirizzo del service CIDR.
| Impostazione | Default | Flag |
|---|---|---|
| Pod CIDR | 10.42.0.0/16 | --cluster-cidr |
| Service CIDR | 10.43.0.0/16 | --service-cidr |
| Cluster DNS | 10.43.0.10 | --cluster-dns |
| Dominio del cluster | cluster.local | --cluster-domain |
| Backend Flannel | vxlan | --flannel-backend |
Se gli intervalli predefiniti si sovrappongono alla rete esistente, vanno cambiati su tutti i server. Per usare una CNI propria si disabilita Flannel e si installa il plugin scelto:
curl -sfL https://get.k3s.io | sh -s - server --cluster-cidr=10.200.0.0/16 --service-cidr=10.201.0.0/16
curl -sfL https://get.k3s.io | sh -s - server --flannel-backend=none --disable-network-policy
8472/UDP
non va esposta a Internet. Flannel usa il bridge CNI e pod con
NET_RAW potrebbero sfruttarlo per attacchi di tipo ARP
spoofing: limitare NET_RAW ai pod non fidati.
Ingress, ServiceLB e Gateway API
Traefik è l'Ingress controller predefinito:
espone un Service di tipo LoadBalancer sulle porte 80 e
443. ServiceLB (klipper-lb) realizza quel
LoadBalancer usando le porte host dei nodi; per default usa tutti i
nodi del cluster, quindi le porte 80 e 443 non sono più
disponibili per altri pod HostPort o NodePort.
Traefik si personalizza con un HelmChartConfig nella
directory dei manifest, non modificando il manifest generato. Per
rimuoverlo: --disable=traefik. La Gateway
API è supportata da Traefik v3 e si abilita con
providers.kubernetesGateway.enabled: true.
Con --disable=servicelb si rinuncia al LoadBalancer
integrato: in quel caso serve un load balancer esterno o un altro
controller.
Storage
k3s include local-path-provisioner, che crea volumi
persistenti sul disco del nodo in
/var/lib/rancher/k3s/storage. La StorageClass predefinita
si chiama local-path ed è adatta a test e a
cluster piccoli; non replica i dati tra nodi.
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: dati
spec:
accessModes:
- ReadWriteOnce
storageClassName: local-path
resources:
requests:
storage: 1Gi
Per volumi condivisi o replicati serve una CSI esterna (Longhorn, Ceph, NFS, un provider cloud). I server sono programmabili per default: se non si vogliono workload sul control plane, applicare un taint.
Registry privato
containerd legge /etc/rancher/k3s/registries.yaml
all'avvio. Il file va presente su ogni nodo che deve
scaricare immagini dal registry, server compresi se eseguono pod.
mirrors:
docker.io:
endpoint:
- "https://registry.example.com:5000"
configs:
"registry.example.com:5000":
auth:
username: utente
password: password
tls:
ca_file: /etc/ssl/certs/registry-ca.pem
insecure_skip_verify: false
mirrors definisce gli endpoint, configs
credenziali e TLS. Il rewrite permette di cambiare il nome
dell'immagine durante il pull. Dopo la modifica va riavviato k3s.
Sicurezza
- Token: il token del server equivale a un accesso amministrativo. Conservarlo con cura e usare token bootstrap temporanei per i join.
- Secret cifrati: abilitare
--secrets-encryptionfin dal primo avvio; il provider predefinito èaescbc, in alternativasecretbox. - Certificati: foglia a 365 giorni con rinnovo automatico a 120 giorni; CA a 10 anni. Controllare con
k3s certificate check. - Firewall: esporre solo le porte necessarie; in particolare non pubblicare
8472/UDP,2379e2380. - Pod: limitare
NET_RAWe usare le NetworkPolicy; k3s include il controller kube-router. - Hardening: seguire la guida CIS di k3s e verificare il cluster con i test di autovalutazione.
Backup e ripristino
La procedura dipende dal datastore. Con SQLite si copia
/var/lib/rancher/k3s/server/db/; con etcd incorporato si
usano gli snapshot; con un database esterno si usano gli strumenti
del DBMS.
/var/lib/rancher/k3s/server/token. Il token è la
passphrase che protegge i dati riservati dello snapshot: senza,
il backup non è ripristinabile.
Uno snapshot contiene l'intero datastore, le CA e le chiavi private; se la cifratura dei secret è attiva, contiene anche la configurazione e le chiavi di cifratura. Va trattato come materiale altamente sensibile.
Air-gap e registry distribuito
In air-gap le immagini possono essere importate dal tar nella
directory /var/lib/rancher/k3s/agent/images/. Ogni avvio
reimporta gli archivi, a meno che non si crei
.cache.json nella stessa directory: in quel caso
l'import avviene solo se dimensione e data di modifica cambiano.
k3s include anche un registry OCI distribuito: con
--embedded-registry le immagini presenti nello store di
un nodo possono essere servite agli altri nodi del cluster, senza un
registry esterno. Le porte 5001/TCP e
6443/TCP devono essere raggiungibili tra i nodi.
Aggiornamenti e version skew
k3s segue il version skew di Kubernetes: si sale di
una minor alla volta e si aggiornano prima i server, poi gli agent.
I canali principali sono stable (default),
latest e i canali per minor, per esempio
v1.37.
curl -sfL https://get.k3s.io | INSTALL_K3S_CHANNEL=stable sh -
curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION=v1.37.2+k3s1 sh -
Per aggiornamenti automatici si può usare il
system-upgrade-controller; in air-gap vanno
predisposte nel registry le immagini del controller, di
rancher/k3s-upgrade e di kubectl.
Troubleshooting
| Sintomo | Dove guardare | Comando utile |
|---|---|---|
| Il servizio non parte | Log di systemd e prerequisiti | sudo journalctl -u k3s -n 200 |
| Prerequisiti mancanti | Cgroup, moduli, porte | sudo k3s check-config |
| Un pod non parte | Eventi e stato del container | sudo k3s kubectl describe pod <NOME> |
| Problemi di runtime | Container e immagini | sudo k3s crictl ps -a |
| Il nodo non si unisce | Token, porta 6443, hostname | sudo journalctl -u k3s-agent -f |
| Nodo con nome già usato | Node password secret | kubectl delete node <NOME> |
| Rete instabile | Porta VXLAN o CNI | sudo k3s kubectl get pods -n kube-system |
| Stato sporco dopo test | Container e iptables | sudo k3s-killall.sh |
Domande frequenti
k3s supporta Windows?
No, k3s non supporta nativamente Windows. I nodi devono essere Linux; per lavorare da Windows si può usare una macchina Linux remota o una distribuzione Linux in WSL, ma non è un ambiente supportato ufficialmente come nodo k3s.
Dove sono i log?
Con l'installazione via script i log del servizio sono in
journalctl -u k3s (o k3s-agent). I log dei
container si leggono con kubectl logs o
crictl logs.
Posso usare il mio Ingress al posto di Traefik?
Sì: avviare tutti i server con --disable=traefik
e installare l'Ingress controller scelto.
Posso convertire un cluster SQLite in etcd?
Sì: basta riavviare il server con --cluster-init.
Da quel momento si possono aggiungere altri server. Se k3s trova
già un datastore etcd su disco, i flag di inizializzazione
vengono ignorati.
Dove stanno i dati?
In /var/lib/rancher/k3s, salvo diverso
--data-dir. Kubeconfig e configurazione stanno in
/etc/rancher/k3s.