IT

Applicazioni

Installare Kubernetes con K3s

Installa K3s su Debian o Ubuntu, usa kubectl, distribuisci una prima applicazione, aggiungi un nodo e proteggi le porte del cluster.

8 min di lettura, aggiornato il 18 novembre 2026

In questa pagina

I tuoi valori

Inseriscili una volta: i comandi della guida si aggiornano.

K3s è una distribuzione Kubernetes leggera e certificata, distribuita come un unico binario. È adatta a un VPS o a un server dedicato: include infatti kubectl, il controller Ingress Traefik, un semplice bilanciatore di carico e uno storage locale.

Questa guida ti accompagna dall'installazione fino a un cluster a due nodi, con Debian 12/13 o Ubuntu 22.04/24.04:

  1. installare il nodo server;
  2. usare kubectl senza esporre l'API;
  3. distribuire una prima applicazione;
  4. aggiungere un nodo agent;
  5. aggiornare ed eseguire il backup del cluster.

Ordinare un server

Per ospitare il tuo cluster, HostMyServers offre diverse opzioni:

Prerequisiti

Ruolo CPU minima RAM minima
Server 2 core 2 GB
Agent 1 core 512 MB

Questi valori, tratti dalla documentazione di K3s, non comprendono le risorse delle tue applicazioni.

Ti servono inoltre:

  • un accesso SSH con un utente che dispone di sudo;
  • un nome host diverso su ogni nodo;
  • un indirizzo IP raggiungibile dagli altri nodi, in genere l'indirizzo IP pubblico;
  • il modulo del kernel WireGuard, se i tuoi nodi comunicano tramite Internet.

Verifica la presenza di WireGuard su ogni nodo:

Terminale
sudo modprobe wireguard && lsmod | grep wireguard

Porte

Porta Protocollo Origine Utilizzo
22 TCP Il tuo computer SSH e tunnel verso l'API
6443 TCP Agent API Kubernetes e supervisore K3s
10250 TCP Tutti i nodi Metriche e API del kubelet
51820 UDP Tutti i nodi Flannel WireGuard su IPv4
51821 UDP Tutti i nodi Flannel WireGuard su IPv6, se utilizzato
80, 443 TCP Internet Applicazioni pubblicate da Traefik

Preparare il server

Terminale
sudo apt update
sudo apt upgrade -y
sudo apt install -y curl ufw

La documentazione di K3s consiglia di disattivare UFW, ma un server esposto su Internet deve restare filtrato. Se mantieni UFW, come qui, le reti interne di K3s devono essere autorizzate. Sostituisci 22 se usi un'altra porta SSH:

Terminale
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow 22/tcp
sudo ufw allow 80,443/tcp
sudo ufw allow from 10.42.0.0/16 to any
sudo ufw allow from 10.43.0.0/16 to any
sudo ufw enable

10.42.0.0/16 è la rete predefinita dei pod e 10.43.0.0/16 quella dei servizi.

Installare il nodo server

Prepara la configurazione prima dell'installazione. In questo modo la rete del cluster è cifrata fin dall'inizio, e potrai aggiungere più avanti un nodo tramite Internet.

Terminale
sudo mkdir -p /etc/rancher/k3s
sudo nano /etc/rancher/k3s/config.yaml
YAML
node-external-ip: IP_DEL_TUO_SERVER
flannel-backend: wireguard-native
flannel-external-ip: true
tls-san:
  - IP_DEL_TUO_SERVER

Installa poi K3s con lo script ufficiale, che per impostazione predefinita segue il canale stable:

Terminale
curl -sfL https://get.k3s.io | sh -

Verifica il servizio e il nodo. Il passaggio allo stato Ready può richiedere un minuto:

Terminale
sudo systemctl status k3s --no-pager
sudo k3s kubectl get nodes -o wide
sudo k3s kubectl get pods -A

Usare kubectl

Il file /etc/rancher/k3s/k3s.yaml dà un accesso amministrativo completo al cluster ed è leggibile solo da root. Non renderlo leggibile da tutti. Crea invece una copia personale:

Terminale
mkdir -p ~/.kube
install -m 600 /dev/null ~/.kube/config
sudo k3s kubectl config view --raw > ~/.kube/config
echo 'export KUBECONFIG="$HOME/.kube/config"' >> ~/.bashrc
export KUBECONFIG="$HOME/.kube/config"
kubectl get nodes

Amministrare il cluster dal tuo computer

Il tunnel SSH evita di aprire la porta 6443 al tuo computer. Installa kubectl sulla tua macchina, poi copia la configurazione:

Terminale
mkdir -p ~/.kube
scp TUO_USER@IP_DEL_TUO_SERVER:.kube/config ~/.kube/k3s-hms
chmod 600 ~/.kube/k3s-hms
ssh -N -L 6443:127.0.0.1:6443 TUO_USER@IP_DEL_TUO_SERVER

Lascia aperto questo tunnel e, in un altro terminale:

Terminale
export KUBECONFIG=~/.kube/k3s-hms
kubectl get nodes

K3s rinnova i certificati del suo file di amministrazione a ogni avvio. Se la tua copia smette di funzionare, copiala di nuovo.

Distribuire una prima applicazione

Crea un manifest:

Terminale
nano demo.yaml
YAML
apiVersion: v1
kind: Namespace
metadata:
  name: demo
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
  namespace: demo
spec:
  replicas: 2
  selector:
    matchLabels:
      app: web
  template:
    metadata:
      labels:
        app: web
    spec:
      containers:
        - name: nginx
          image: nginx:stable-alpine
          ports:
            - containerPort: 80
          resources:
            requests:
              cpu: 50m
              memory: 32Mi
            limits:
              memory: 128Mi
---
apiVersion: v1
kind: Service
metadata:
  name: web
  namespace: demo
spec:
  selector:
    app: web
  ports:
    - port: 80
      targetPort: 80
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: web
  namespace: demo
spec:
  ingressClassName: traefik
  rules:
    - host: demo.tuo-dominio.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: web
                port:
                  number: 80

Applicalo e segui la distribuzione:

Terminale
kubectl apply -f demo.yaml
kubectl -n demo rollout status deployment/web
kubectl -n demo get pods,svc,ingress

Prova l'applicazione dal tuo computer, anche se il DNS non è ancora configurato:

Terminale
curl -H 'Host: demo.tuo-dominio.com' http://IP_DEL_TUO_SERVER/

Devi ottenere la pagina di benvenuto di Nginx.

Elimina l'esempio quando non ti serve più:

Terminale
kubectl delete namespace demo

Aggiungere un nodo agent

In questa sezione, IP_AGENT indica l'indirizzo IP del nuovo nodo.

Aprire i flussi tra i nodi

Sul server:

Terminale
sudo ufw allow from IP_AGENT to any port 6443 proto tcp
sudo ufw allow from IP_AGENT to any port 10250 proto tcp
sudo ufw allow from IP_AGENT to any port 51820 proto udp

Sull'agent:

Terminale
sudo apt update
sudo apt install -y curl ufw
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow 22/tcp
sudo ufw allow 80,443/tcp
sudo ufw allow from 10.42.0.0/16 to any
sudo ufw allow from 10.43.0.0/16 to any
sudo ufw allow from IP_DEL_TUO_SERVER to any port 10250 proto tcp
sudo ufw allow from IP_DEL_TUO_SERVER to any port 51820 proto udp
sudo ufw enable

Le porte 80 e 443 sono necessarie sull'agent, perché Traefik può essere pubblicato su ogni nodo. Con più di due nodi, apri le porte 10250/TCP e 51820/UDP tra tutti i nodi.

Unirsi al cluster

Sul server, mostra il token:

Terminale
sudo cat /var/lib/rancher/k3s/server/node-token

Sull'agent, dichiara il suo indirizzo esterno, poi avvia l'installazione. Il comando read attende che tu incolli il token, senza mostrarlo né salvarlo nella cronologia:

Terminale
sudo mkdir -p /etc/rancher/k3s
echo 'node-external-ip: IP_AGENT' | sudo tee /etc/rancher/k3s/config.yaml
read -rs K3S_TOKEN
curl -sfL https://get.k3s.io | K3S_URL=https://IP_DEL_TUO_SERVER:6443 K3S_TOKEN="$K3S_TOKEN" sh -
unset K3S_TOKEN
sudo systemctl status k3s-agent --no-pager

Sul server, il nuovo nodo deve comparire nello stato Ready:

Terminale
kubectl get nodes -o wide

Aggiornare K3s

Esegui prima il backup del cluster e leggi le note di rilascio. Aggiorna prima i server, uno alla volta, poi gli agent, senza saltare nessuna versione minore di Kubernetes.

Sul server, esegui di nuovo lo script. La configurazione di config.yaml viene mantenuta:

Terminale
curl -sfL https://get.k3s.io | sh -

Su ogni agent, ripassa le stesse variabili:

Terminale
read -rs K3S_TOKEN
curl -sfL https://get.k3s.io | K3S_URL=https://IP_DEL_TUO_SERVER:6443 K3S_TOKEN="$K3S_TOKEN" sh -
unset K3S_TOKEN

Se il tuo cluster è indietro di più versioni minori, sali per gradi con il canale corrispondente, ad esempio:

Terminale
curl -sfL https://get.k3s.io | INSTALL_K3S_CHANNEL=v1.36 sh -

Controlla poi le versioni con kubectl get nodes.

Eseguire backup e ripristino

Con SQLite, salva il database e il token del server: senza questo token, il backup è inutilizzabile. Fermare K3s garantisce una copia coerente e non arresta i container già avviati.

Terminale
sudo systemctl stop k3s
sudo tar -czpf "/root/k3s-$(date +%F).tar.gz" /var/lib/rancher/k3s/server/db /var/lib/rancher/k3s/server/token /etc/rancher/k3s/config.yaml
sudo systemctl start k3s
sudo chmod 600 /root/k3s-*.tar.gz

I volumi creati dallo storage locale si trovano in /var/lib/rancher/k3s/storage. Salvali anche, idealmente con gli strumenti propri di ogni applicazione, ad esempio un'esportazione del database. Conserva inoltre i tuoi manifest in un repository Git privato.

Per ripristinare il database sul server:

Terminale
sudo systemctl stop k3s
sudo rm -rf /var/lib/rancher/k3s/server/db
sudo tar -xzpf /root/k3s-AAAA-MM-GG.tar.gz -C /
sudo systemctl start k3s
kubectl get nodes

In caso di problemi

Unable to read /etc/rancher/k3s/k3s.yaml

Il tuo utente non ha accesso al file di amministrazione. Riprendi la sezione Usare kubectl e verifica echo $KUBECONFIG. Evita di rendere questo file leggibile da tutti con --write-kubeconfig-mode 644.

Il servizio k3s non si avvia

Terminale
sudo journalctl -u k3s -n 80 --no-pager
sudo k3s check-config

Se i log citano WireGuard, verifica sudo modprobe wireguard. Quando il modulo non è disponibile su un cluster con un solo nodo, rimuovi flannel-backend e flannel-external-ip da config.yaml prima di una nuova installazione. Non sostituire WireGuard con VXLAN tra nodi collegati tramite Internet.

L'agent non entra nel cluster

Terminale
sudo journalctl -u k3s-agent -n 80 --no-pager
curl -vk -m 5 https://IP_DEL_TUO_SERVER:6443/ping
  • connection refused o timeout: verifica UFW e l'indirizzo di K3S_URL.
  • token non valido: copia di nuovo il contenuto di node-token.
  • Node password rejected, duplicate hostname: un altro nodo ha lo stesso nome, oppure questo nodo è già stato registrato. Cambia il nome host, oppure elimina il vecchio nodo con kubectl delete node NOME_NODO.

Un nodo resta nello stato NotReady

Terminale
kubectl describe node NOME_NODO
ip link show flannel-wg

Verifica le porte 10250/TCP e 51820/UDP tra i nodi, così come i valori node-external-ip.

Un pod resta in Pending o ImagePullBackOff

Terminale
kubectl -n demo describe pod NOME_POD
kubectl -n demo logs NOME_POD

Pending segnala spesso una carenza di CPU o di memoria. ImagePullBackOff indica un nome di immagine errato, un accesso negato al registry o un limite di download.

L'Ingress restituisce 404 o le porte 80/443 non rispondono

Terminale
kubectl -n kube-system get pods,svc | grep -E 'traefik|svclb'
sudo ss -tlnp | grep -E ':(80|443)\b'

Un 404 indica in genere che l'intestazione Host non corrisponde al campo host dell'Ingress. Se i pod svclb restano in Pending, un servizio di sistema, come Nginx o Apache, occupa probabilmente già le porte 80 e 443.

Disinstallare K3s

Terminale
/usr/local/bin/k3s-uninstall.sh

Su un agent:

Terminale
/usr/local/bin/k3s-agent-uninstall.sh

Per approfondire

Per archiviare le tue immagini di container, consulta la guida Installare Harbor. Per automatizzare la preparazione dei tuoi nodi, consulta Automatizzare i tuoi server con Ansible.

Riferimenti