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.
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:
- installare il nodo server;
- usare
kubectlsenza esporre l'API; - distribuire una prima applicazione;
- aggiungere un nodo agent;
- 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:
sudo modprobe wireguard && lsmod | grep wireguardPorte
| 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
sudo apt update
sudo apt upgrade -y
sudo apt install -y curl ufwLa 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:
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 enable10.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.
sudo mkdir -p /etc/rancher/k3s
sudo nano /etc/rancher/k3s/config.yamlnode-external-ip: IP_DEL_TUO_SERVER
flannel-backend: wireguard-native
flannel-external-ip: true
tls-san:
- IP_DEL_TUO_SERVERInstalla poi K3s con lo script ufficiale, che per impostazione predefinita segue il canale stable:
curl -sfL https://get.k3s.io | sh -Verifica il servizio e il nodo. Il passaggio allo stato Ready può richiedere un minuto:
sudo systemctl status k3s --no-pager
sudo k3s kubectl get nodes -o wide
sudo k3s kubectl get pods -AUsare 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:
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 nodesAmministrare 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:
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_SERVERLascia aperto questo tunnel e, in un altro terminale:
export KUBECONFIG=~/.kube/k3s-hms
kubectl get nodesK3s 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:
nano demo.yamlapiVersion: 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: 80Applicalo e segui la distribuzione:
kubectl apply -f demo.yaml
kubectl -n demo rollout status deployment/web
kubectl -n demo get pods,svc,ingressProva l'applicazione dal tuo computer, anche se il DNS non è ancora configurato:
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ù:
kubectl delete namespace demoAggiungere un nodo agent
In questa sezione, IP_AGENT indica l'indirizzo IP del nuovo nodo.
Aprire i flussi tra i nodi
Sul server:
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 udpSull'agent:
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 enableLe 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:
sudo cat /var/lib/rancher/k3s/server/node-tokenSull'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:
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-pagerSul server, il nuovo nodo deve comparire nello stato Ready:
kubectl get nodes -o wideAggiornare 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:
curl -sfL https://get.k3s.io | sh -Su ogni agent, ripassa le stesse variabili:
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_TOKENSe il tuo cluster è indietro di più versioni minori, sali per gradi con il canale corrispondente, ad esempio:
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.
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.gzI 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:
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 nodesIn 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
sudo journalctl -u k3s -n 80 --no-pager
sudo k3s check-configSe 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
sudo journalctl -u k3s-agent -n 80 --no-pager
curl -vk -m 5 https://IP_DEL_TUO_SERVER:6443/pingconnection refusedo timeout: verifica UFW e l'indirizzo diK3S_URL.tokennon valido: copia di nuovo il contenuto dinode-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 conkubectl delete node NOME_NODO.
Un nodo resta nello stato NotReady
kubectl describe node NOME_NODO
ip link show flannel-wgVerifica le porte 10250/TCP e 51820/UDP tra i nodi, così come i valori node-external-ip.
Un pod resta in Pending o ImagePullBackOff
kubectl -n demo describe pod NOME_POD
kubectl -n demo logs NOME_PODPending 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
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
/usr/local/bin/k3s-uninstall.shSu un agent:
/usr/local/bin/k3s-agent-uninstall.shPer 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.