Setup Cluster Kubernetes con kubeadm: Guida Pratica 2026

Tutorial pratico per amministratori e team DevOps: tutti i comandi kubeadm e le decisioni architetturali per fare il setup di un cluster Kubernetes self-hosted su Ubuntu 22.04 — dal singolo nodo al production HA con 3 control plane, CNI, storage persistente, backup di etcd e upgrade rolling.

Per chi è questa guida: chi vuole imparare a installare e gestire un cluster Kubernetes con kubeadm, capire l'architettura control-plane/worker, e arrivare a un setup pronto per produzione. Cosa non è: non parla di workload onboarding, GitOps o integrazione applicativa — qui si parte da zero macchine Ubuntu e si arriva a kubectl get nodes Ready.

# 1. Install containerd + kubeadm/kubelet/kubectl
sudo apt update && sudo apt install -y containerd kubeadm kubelet kubectl
sudo systemctl enable --now containerd kubelet

# 2. Init del control plane
sudo kubeadm init --pod-network-cidr=10.244.0.0/16

# 3. Config kubectl per il tuo user
mkdir -p ~/.kube && sudo cp /etc/kubernetes/admin.conf ~/.kube/config && sudo chown $(id -u):$(id -g) ~/.kube/config

# 4. Installa CNI (Flannel) e rimuovi taint dal control plane (single-node)
kubectl apply -f https://github.com/flannel-io/flannel/releases/latest/download/kube-flannel.yml
kubectl taint nodes --all node-role.kubernetes.io/control-plane-

# 5. Verifica
kubectl get nodes  # Status: Ready dopo ~60s

Hai visto sopra i 4 comandi che ti tirano su un cluster in 5 minuti. Adesso la domanda diventa quando usarli e come scalare. Cloud managed o self-hosted? Quale distribuzione? Quanti nodi? Questa guida copre le scelte chiave e mostra il setup concreto con kubeadm, dal singolo nodo al production HA.

Prima Decisione: Managed vs Self-Hosted

La prima scelta e se gestire Kubernetes tu stesso o lasciarlo fare a qualcun altro.

Kubernetes Managed (Cloud)

I cloud provider offrono Kubernetes as a Service:

• EKS (AWS)
• GKE (Google Cloud)
• AKS (Azure)
• DOKS (DigitalOcean)

Pro:

• Control plane gestito — non devi preoccuparti di etcd, API server, scheduler
• Upgrade semplificati
• Connessione nativa a servizi cloud (load balancer, storage, IAM)
• Supporto dal provider

Contro:

• Costo — paghi per il control plane oltre ai worker node
• Vendor lock-in — le integrazioni native ti legano al provider
• Meno controllo — alcune configurazioni non sono possibili

Quando sceglierlo: Se sei su cloud e non vuoi gestire l'infrastruttura Kubernetes. Per la maggior parte dei casi produzione enterprise, e la scelta ragionevole.

Self-Hosted

Installi e gestisci tutto tu. Le opzioni:

• kubeadm — Tool ufficiale per bootstrap cluster
• K3s — Kubernetes leggero (ne ho parlato in un altro articolo)
• RKE2 (Rancher) — Kubernetes enterprise-ready
• Kubespray — Ansible playbook per deployment

Pro:

• Controllo totale
• Nessun costo per il control plane
• Funziona ovunque (cloud, on-premise, bare metal)

Contro:

• Responsabilita di upgrade, backup, high availability
• Piu complessita operativa
• Niente supporto (a meno di non pagare per una distribuzione commerciale)

Quando sceglierlo: On-premise, edge computing, requisiti di controllo specifici, o quando vuoi imparare come funziona Kubernetes davvero.

Architettura del Cluster

Prima di creare il cluster, alcune decisioni architetturali.

Quanti Control Plane Node?

• 1 nodo: Ok per sviluppo e test. Se muore, perdi il cluster.
• 3 nodi: Minimo per produzione con HA. Quorum etcd richiede dispari.
• 5 nodi: Per cluster molto critici. Piu di 5 raramente serve.

Quanti Worker Node?

Dipende dal workload. Inizia con quello che ti serve, scala dopo. Kubernetes rende facile aggiungere nodi.

Considera:

• Risorse necessarie per i tuoi pod
• Margine per scheduling (non vuoi nodi al 100%)
• Fault tolerance (se un nodo muore, gli altri reggono?)

Networking CNI

Il Container Network Interface (CNI) gestisce il networking tra pod. Opzioni comuni:

• Calico — Il piu usato. Network policy, BGP, flessibile.
• Cilium — Basato su eBPF, performance eccellenti, feature avanzate.
• Flannel — Semplice, leggero, niente network policy.
• Weave — Facile da configurare, encryption built-in.

Per la maggior parte dei casi, Calico va bene. Se hai requisiti di performance o sicurezza avanzati, guarda Cilium.

Setup con kubeadm

Vediamo un setup pratico con kubeadm su Ubuntu 22.04. Questo e il metodo "ufficiale" per creare cluster self-hosted.

Prerequisiti (Tutti i Nodi)

# Disabilita swap (Kubernetes lo richiede)
sudo swapoff -a
sudo sed -i '/ swap / s/^\(.*\)$/#\1/g' /etc/fstab

# Carica moduli kernel necessari
cat <<EOF | sudo tee /etc/modules-load.d/k8s.conf
overlay
br_netfilter
EOF

sudo modprobe overlay
sudo modprobe br_netfilter

# Configura sysctl
cat <<EOF | sudo tee /etc/sysctl.d/k8s.conf
net.bridge.bridge-nf-call-iptables  = 1
net.bridge.bridge-nf-call-ip6tables = 1
net.ipv4.ip_forward                 = 1
EOF

sudo sysctl --system

Installa Container Runtime (containerd)

# Installa containerd
sudo apt-get update
sudo apt-get install -y containerd

# Configura containerd
sudo mkdir -p /etc/containerd
containerd config default | sudo tee /etc/containerd/config.toml

# Abilita SystemdCgroup
sudo sed -i 's/SystemdCgroup = false/SystemdCgroup = true/g' /etc/containerd/config.toml

sudo systemctl restart containerd
sudo systemctl enable containerd

Installa kubeadm, kubelet, kubectl

# Aggiungi repository Kubernetes
sudo apt-get update
sudo apt-get install -y apt-transport-https ca-certificates curl gpg

curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.29/deb/Release.key | sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg

echo 'deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.29/deb/ /' | sudo tee /etc/apt/sources.list.d/kubernetes.list

# Installa i pacchetti
sudo apt-get update
sudo apt-get install -y kubelet kubeadm kubectl
sudo apt-mark hold kubelet kubeadm kubectl

Inizializza il Control Plane

Sul primo nodo control plane:

sudo kubeadm init \
  --control-plane-endpoint="LOAD_BALANCER_IP:6443" \
  --upload-certs \
  --pod-network-cidr=10.244.0.0/16

Se hai un solo control plane, puoi omettere --control-plane-endpoint. Il --pod-network-cidr dipende dal CNI che userai (10.244.0.0/16 e per Flannel, per Calico puoi usare altri range).

Dopo il completamento, kubeadm ti da:

1. Comando per configurare kubectl
2. Comando per joinare altri control plane
3. Comando per joinare worker

# Configura kubectl per il tuo utente
mkdir -p $HOME/.kube
sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
sudo chown $(id -u):$(id -g) $HOME/.kube/config

Installa CNI (Calico)

kubectl apply -f https://raw.githubusercontent.com/projectcalico/calico/v3.27.0/manifests/calico.yaml

Aspetta che i pod Calico siano running:

kubectl get pods -n kube-system

Joina i Worker Node

Su ogni worker node, esegui il comando che kubeadm ti ha dato:

sudo kubeadm join CONTROL_PLANE_IP:6443 \
  --token TOKEN \
  --discovery-token-ca-cert-hash sha256:HASH

Se il token e scaduto, generane uno nuovo sul control plane:

kubeadm token create --print-join-command

Verifica il Cluster

kubectl get nodes

Dovresti vedere tutti i nodi in stato Ready.

High Availability

Per HA del control plane servono almeno 3 nodi. La configurazione e simile ma con alcuni accorgimenti.

Load Balancer

Serve un load balancer davanti ai control plane. Opzioni:

• HAProxy
• Nginx
• Cloud load balancer
• kube-vip (software load balancer per Kubernetes)

Il load balancer deve bilanciare la porta 6443 (API server) su tutti i control plane.

Setup HA

# Primo control plane
sudo kubeadm init \
  --control-plane-endpoint="LOAD_BALANCER_IP:6443" \
  --upload-certs \
  --pod-network-cidr=10.244.0.0/16

# Altri control plane
sudo kubeadm join LOAD_BALANCER_IP:6443 \
  --token TOKEN \
  --discovery-token-ca-cert-hash sha256:HASH \
  --control-plane \
  --certificate-key CERT_KEY

Il --certificate-key viene mostrato nell'output del primo kubeadm init.

Storage

Kubernetes ha bisogno di storage per i volumi persistenti. Opzioni:

Cloud: Usa il CSI driver del tuo provider (EBS per AWS, PD per GCP, etc.)

Self-hosted:

• Longhorn — Storage distribuito, facile da installare
• Rook/Ceph — Potente ma complesso
• OpenEBS — Piu semplice di Ceph, varie opzioni di backend
• Local Path Provisioner — Storage locale, niente replica

Per iniziare, Local Path Provisioner va bene:

kubectl apply -f https://raw.githubusercontent.com/rancher/local-path-provisioner/master/deploy/local-path-storage.yaml

Per produzione, considera Longhorn o il driver CSI del tuo storage.

Monitoring e Logging

Un cluster senza monitoring e una bomba a orologeria.

Metrics Server

Necessario per kubectl top e autoscaling:

kubectl apply -f https://github.com/kubernetes-sigs/metrics-server/releases/latest/download/components.yaml

Prometheus + Grafana

helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
helm install prometheus prometheus-community/kube-prometheus-stack

Questo installa Prometheus, Grafana, e dashboard pre-configurate per Kubernetes.

Upgrade del Cluster

Kubernetes rilascia versioni ogni 4 mesi circa. Come aggiornare:

Control Plane

# Trova la versione disponibile
apt-cache madison kubeadm

# Upgrade kubeadm
sudo apt-mark unhold kubeadm
sudo apt-get update && sudo apt-get install -y kubeadm=1.30.0-1.1
sudo apt-mark hold kubeadm

# Verifica il piano di upgrade
sudo kubeadm upgrade plan

# Applica l'upgrade
sudo kubeadm upgrade apply v1.30.0

# Upgrade kubelet e kubectl
sudo apt-mark unhold kubelet kubectl
sudo apt-get update && sudo apt-get install -y kubelet=1.30.0-1.1 kubectl=1.30.0-1.1
sudo apt-mark hold kubelet kubectl

sudo systemctl daemon-reload
sudo systemctl restart kubelet

Worker Node

# Sul control plane: drain il nodo
kubectl drain NODE_NAME --ignore-daemonsets

# Sul worker: upgrade
sudo apt-mark unhold kubeadm kubelet kubectl
sudo apt-get update && sudo apt-get install -y kubeadm=1.30.0-1.1 kubelet=1.30.0-1.1 kubectl=1.30.0-1.1
sudo apt-mark hold kubeadm kubelet kubectl

sudo kubeadm upgrade node
sudo systemctl daemon-reload
sudo systemctl restart kubelet

# Sul control plane: uncordon il nodo
kubectl uncordon NODE_NAME

Ripeti per ogni worker, uno alla volta.

Backup

Backup di etcd e critico. Se perdi etcd, perdi il cluster.

# Backup
ETCDCTL_API=3 etcdctl snapshot save backup.db \
  --endpoints=https://127.0.0.1:2379 \
  --cacert=/etc/kubernetes/pki/etcd/ca.crt \
  --cert=/etc/kubernetes/pki/etcd/server.crt \
  --key=/etc/kubernetes/pki/etcd/server.key

# Verifica
ETCDCTL_API=3 etcdctl snapshot status backup.db

Automatizza questo backup con un CronJob o script esterno. Conserva i backup off-site.

Alternative a kubeadm

kubeadm e il metodo standard ma non l'unico.

Kubespray: Ansible playbook che automatizza tutto. Buono se conosci gia Ansible e vuoi deployment ripetibili.

RKE2: Distribuzione Rancher. Include hardening di sicurezza, piu facile da gestire di vanilla kubeadm.

K3s: Se non hai bisogno di tutte le feature di Kubernetes standard. Molto piu semplice.

Talos Linux: OS immutabile fatto apposta per Kubernetes. Interessante per chi vuole sicurezza e immutabilita.

Conclusione

Creare un cluster Kubernetes non e difficile, ma richiede attenzione ai dettagli. Le decisioni prese all'inizio (HA, networking, storage) influenzano tutto quello che viene dopo.

Se sei su cloud e non hai requisiti particolari, usa il managed Kubernetes del tuo provider. E la scelta pragmatica.

Se devi andare self-hosted, kubeadm e il punto di partenza standard. Investi tempo in automazione (Ansible, Terraform) cosi puoi ricreare il cluster velocemente se qualcosa va storto.

E soprattutto: testa gli upgrade e i recovery prima di andare in produzione. Scoprire che il tuo backup non funziona durante un'emergenza e un'esperienza che vuoi evitare.

Un cluster Kubernetes e facile da creare. Un cluster Kubernetes affidabile richiede pianificazione e manutenzione continua.