Creare un cluster Ku­ber­ne­tes su Proxmox: guida

La creazione di un cluster Ku­ber­ne­tes su Proxmox ti permette di gestire in un ambiente vir­tua­liz­za­to e auto-ospitato una piat­ta­for­ma per­for­man­te di or­che­stra­zio­ne dei container. Questa soluzione è par­ti­co­lar­men­te adatta ad ambienti di test, flussi di lavoro di sviluppo e CI o anche a scenari pro­dut­ti­vi di piccole di­men­sio­ni. In questa guida scoprirai come con­fi­gu­ra­re macchine virtuali su Proxmox e costruire su di esse un cluster Ku­ber­ne­tes stabile.

Primo passaggio: verifica i pre­re­qui­si­ti

Prima di iniziare con la vera e propria con­fi­gu­ra­zio­ne del cluster Ku­ber­ne­tes, dovresti as­si­cu­rar­ti che il tuo ambiente soddisfi tutti i pre­re­qui­si­ti tecnici. Una base pulita ti farà ri­spar­mia­re molto tempo in seguito ed evita errori di con­fi­gu­ra­zio­ne.

Per prima cosa ti serve un’in­stal­la­zio­ne fun­zio­nan­te di Proxmox VE. Per motivi di pre­sta­zio­ni si consiglia un’in­stal­la­zio­ne bare metal di Proxmox. Devono essere di­spo­ni­bi­li sia l’accesso web tramite l’in­ter­fac­cia Proxmox sia l’accesso SSH alla riga di comando. Tramite SSH puoi eseguire comandi, caricare immagini e au­to­ma­tiz­za­re con­fi­gu­ra­zio­ni.

Per un cluster Ku­ber­ne­tes stabile hai inoltre bisogno di diverse macchine virtuali. Sono con­si­glia­ti i seguenti nodi Ku­ber­ne­tes:

• un nodo master (per il control plane) e
• almeno due nodi worker.

In questo modo ottieni un certo grado di ri­don­dan­za e puoi eseguire Ku­ber­ne­tes così come previsto nei veri ambienti di pro­du­zio­ne. Per scopi di test è però suf­fi­cien­te anche una con­fi­gu­ra­zio­ne più piccola con un nodo master e uno worker.

Il tuo host Proxmox dovrebbe inoltre disporre di un’in­ter­fac­cia bridge fun­zio­nan­te, che permetta alle macchine virtuali di accedere alla rete locale e, se ne­ces­sa­rio, a internet. Questo è im­por­tan­te affinché le VM possano in seguito scaricare ag­gior­na­men­ti e in­stal­la­re i com­po­nen­ti di Ku­ber­ne­tes.

Secondo passaggio: scarica l’immagine cloud e preparala come template

Le in­stal­la­zio­ni di Ku­ber­ne­tes sono più semplici da rea­liz­za­re con le immagini cloud. Queste immagini di sistema operativo pre­con­fi­gu­ra­te, perlopiù Ubuntu o Debian, sono ot­ti­miz­za­te per l’avvio au­to­ma­ti­co con cloud-init. In questo esempio uti­liz­zia­mo un’immagine cloud Ubuntu 22.04 LTS, perché è stabile, ben do­cu­men­ta­ta e ottimale per l’uso con Ku­ber­ne­tes.

Per prima cosa scarica l’ultima versione dell’immagine cloud di Ubuntu di­ret­ta­men­te sul tuo host Proxmox. Accedi via SSH al tuo server Proxmox e spostati nella cartella in cui Proxmox memorizza i file ISO e le immagini:

cd /var/lib/vz/template/iso

Scarica quindi l’immagine Ubuntu con il seguente comando:

wget -O ubuntu-22.04-server-cloudimg-amd64.img https://cloud-images.ubuntu.com/releases/22.04/release/ubuntu-22.04-server-cloudimg-amd64.img

scp ubuntu-22.04-server-cloudimg-amd64.img root@<proxmox-ip>:/var/lib/vz/template/iso/

Non appena l’immagine si trova sull’host Proxmox, puoi creare da essa una nuova macchina virtuale che fungerà suc­ces­si­va­men­te da template. A questo scopo crea in­nan­zi­tut­to una VM vuota con un ID univoco, ad esempio 9000, e assegnale le risorse hardware di base:

qm create 9000 --name ubuntu-template --memory 2048 --net0 virtio,bridge=vmbr0

Ora importa l’immagine cloud pre­ce­den­te­men­te scaricata come disco rigido virtuale nello spazio di ar­chi­via­zio­ne de­si­de­ra­to (nel nostro esempio local-lvm):

qm importdisk 9000 /var/lib/vz/template/iso/ubuntu-22.04-server-cloudimg-amd64.img local-lvm

Suc­ces­si­va­men­te puoi collegare il disco importato alla VM e impostare il con­trol­ler corretto. In questo modo l’immagine viene associata al con­trol­ler SCSI virtuale della macchina virtuale:

qm set 9000 --scsihw virtio-scsi-pci --scsi0 local-lvm:vm-9000-disk-0

Per impostare au­to­ma­ti­ca­men­te in seguito, durante la clo­na­zio­ne delle VM, indirizzi IP, nomi host e chiavi SSH, hai bisogno di un’unità cloud init. Questa unità virtuale contiene i dati di con­fi­gu­ra­zio­ne applicati au­to­ma­ti­ca­men­te all’avvio della VM. Aggiungi il drive cloud init e definisci l’ordine di boot con i seguenti comandi:

qm set 9000 --ide2 local-lvm:cloudinit
qm set 9000 --boot c --bootdisk scsi0

Attiva anche l’agente ospite di QEMU, così che Proxmox possa in seguito leggere le in­for­ma­zio­ni di stato dalla VM, e configura una console seriale per avere accesso diretto alla console della VM in caso di emergenza:

qm set 9000 --agent 1
qm set 9000 --serial0 socket --vga serial0

Se tutto è con­fi­gu­ra­to cor­ret­ta­men­te, puoi con­ver­ti­re la tua macchina virtuale in un co­sid­det­to template. I template fungono in Proxmox da modello dal quale puoi in seguito creare un numero qualsiasi di cloni. Sono quindi perfetti per i tuoi nodi Ku­ber­ne­tes.

qm template 9000

Dopo questo passaggio, il template Ubuntu è pronto e può essere uti­liz­za­to come base per i tuoi nodi Ku­ber­ne­tes master e worker.

Terzo passaggio: clona le VM per master/worker tramite CLI

Nel terzo passaggio crei, a partire dal template pre­ce­den­te­men­te con­fi­gu­ra­to, le macchine virtuali che in seguito fun­zio­ne­ran­no come nodi master e worker del tuo cluster Ku­ber­ne­tes. Ciascuna di queste VM riceve un proprio indirizzo IP, un nome host univoco e una chiave SSH per l’accesso sicuro. Proxmox gestisce au­to­ma­ti­ca­men­te la con­fi­gu­ra­zio­ne di base tramite cloud-init, così non devi più ef­fet­tua­re alcuna con­fi­gu­ra­zio­ne manuale all’interno delle macchine virtuali.

Clona in­nan­zi­tut­to il template creato in pre­ce­den­za (in questo esempio con l’ID 9000) e crea da esso tre macchine virtuali: una per il nodo master e due per i cor­ri­spon­den­ti nodi worker. In questo caso puoi adattare in modo per­so­na­liz­za­to CPU e RAM:

qm clone 9000 101 --name k8s-master-1 --full true
qm set 101 --cores 2 --memory 4096
qm clone 9000 102 --name k8s-worker-1 --full true
qm set 102 --cores 2 --memory 4096
qm clone 9000 103 --name k8s-worker-2 --full true
qm set 103 --cores 2 --memory 4096

Suc­ces­si­va­men­te definisci tramite cloud-init le im­po­sta­zio­ni di rete di base, il nome host e la chiave SSH. Puoi assegnare indirizzi IP fissi oppure uti­liz­za­re DHCP. In questo esempio vengono uti­liz­za­ti indirizzi statici:

# Configurare il nodo master
qm set 101 --ipconfig0 ip=192.168.1.10/24,gw=192.168.1.1
qm set 101 --sshkey "$(cat ~/.ssh/id_rsa.pub)"
qm set 101 --ciuser ubuntu
qm set 101 --nameserver 192.168.1.1
qm set 101 --description "K8s Master 1"
# Configurare il nodo worker
qm set 102 --ipconfig0 ip=192.168.1.11/24,gw=192.168.1.1
qm set 102 --sshkey "$(cat ~/.ssh/id_rsa.pub)"
qm set 102 --ciuser ubuntu
qm set 103 --ipconfig0 ip=192.168.1.12/24,gw=192.168.1.1
qm set 103 --sshkey "$(cat ~/.ssh/id_rsa.pub)"
qm set 103 --ciuser ubuntu

Infine, avvia tutte e tre le macchine con i comandi del terminale riportati qui di seguito:

qm start 101
qm start 102
qm start 103

Attendi qualche istante finché i sistemi non sono com­ple­ta­men­te avviati, quindi verifica la con­nes­sio­ne via SSH. Se tutto funziona, puoi ad esempio accedere al nodo master con il seguente comando:

ssh ubuntu@192.168.1.10

Quarto passaggio: aggiungi la con­fi­gu­ra­zio­ne di base su tutte le macchine virtuali

Prima di in­stal­la­re Ku­ber­ne­tes sulle VM, dovresti applicare alcune im­po­sta­zio­ni a livello di sistema, ne­ces­sa­rie per un fun­zio­na­men­to stabile. Tra queste rientrano la di­sat­ti­va­zio­ne dello swap, la re­go­la­zio­ne dei parametri del kernel per rete e inoltro dell’indirizzo IP, oltre alla sin­cro­niz­za­zio­ne dell’ora di sistema. Queste misure ga­ran­ti­sco­no che Ku­ber­ne­tes possa operare cor­ret­ta­men­te e che le funzioni di rete all’interno dei container fun­zio­ni­no in modo af­fi­da­bi­le.

Per prima cosa disattiva lo swap su tutti i nodi, poiché Ku­ber­ne­tes lo richiede per la logica dello scheduler. Inoltre, rimuovi la voce cor­ri­spon­den­te in /etc/fstab, in modo che lo swap non venga riat­ti­va­to dopo un riavvio:

sudo swapoff -a
sudo sed -i '/ swap / s/^/#/' /etc/fstab

Suc­ces­si­va­men­te configuri i parametri del kernel per as­si­cu­rar­ti che i pacchetti di rete tra container e nodi possano essere elaborati cor­ret­ta­men­te:

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

Un altro passaggio im­por­tan­te è la sin­cro­niz­za­zio­ne dell’ora di sistema, in modo che cer­ti­fi­ca­ti e com­po­nen­ti del cluster non causino problemi per via di orari non allineati. A questo scopo puoi in­stal­la­re e avviare chrony:

sudo apt update && sudo apt install -y chrony
sudo systemctl enable --now chrony

Infine, è con­si­glia­bi­le in­stal­la­re alcuni strumenti di base che saranno utili nei passaggi suc­ces­si­vi:

sudo apt install -y curl apt-transport-https ca-certificates gnupg lsb-release

Dopo questi passaggi tutti i nodi sono preparati in modo uniforme, lo swap è di­sat­ti­va­to, le im­po­sta­zio­ni di rete sono con­fi­gu­ra­te cor­ret­ta­men­te e l’ora è sin­cro­niz­za­ta. Le tue VM sono ora pronte per l’in­stal­la­zio­ne di Ku­ber­ne­tes e la creazione del tuo cluster.

Quinto passaggio: scegli la di­stri­bu­zio­ne Ku­ber­ne­tes

Prima di iniziare con la vera e propria in­stal­la­zio­ne di Ku­ber­ne­tes, dovresti scegliere una di­stri­bu­zio­ne adatta. In base alle tue esigenze puoi optare tra due varianti con­si­glia­te:

• RKE2 (Rancher Ku­ber­ne­tes Engine 2): RKE2 è una di­stri­bu­zio­ne Ku­ber­ne­tes stabile e pronta per l’ambiente di pro­du­zio­ne, svi­lup­pa­ta da Rancher. È par­ti­co­lar­men­te adatta se in seguito vorresti uti­liz­za­re una gestione grafica tramite Rancher o se prevedi un cluster con più nodi di control plane.
• k3s: k3s è una di­stri­bu­zio­ne Ku­ber­ne­tes leggera, adatta ad ambienti di test, home lab o sistemi con risorse limitate. È molto semplice da in­stal­la­re e richiede meno memoria e CPU.

Per la creazione di un cluster Ku­ber­ne­tes robusto su Proxmox, che possa essere uti­liz­za­to anche in uno scenario vicino alla pro­du­zio­ne, si consiglia RKE2. Se invece desideri con­fi­gu­ra­re ra­pi­da­men­te un piccolo cluster di test o sviluppo, k3s è l’al­ter­na­ti­va più pratica. Nel resto di questa guida verrà uti­liz­za­to RKE2.

Sesto passaggio: installa RKE2 sul nodo master

Dopo aver com­ple­ta­to la con­fi­gu­ra­zio­ne di base delle macchine virtuali puoi iniziare con l’in­stal­la­zio­ne di RKE2 sul nodo master. Per farlo, accedi via SSH al nodo master:

ssh ubuntu@192.168.1.10

Ora scarica lo script di in­stal­la­zio­ne di RKE2 ed eseguilo. Puoi fa­col­ta­ti­va­men­te spe­ci­fi­ca­re un canale con la versione de­si­de­ra­ta:

curl -sfL https://get.rke2.io | sudo INSTALL_RKE2_CHANNEL=v1.28 bash -

Dopo l’in­stal­la­zio­ne attiva il servizio server RKE2 e avvialo im­me­dia­ta­men­te:

sudo systemctl enable --now rke2-server.service

Verifica con il seguente comando che il server RKE2 sia in ese­cu­zio­ne cor­ret­ta­men­te:

sudo systemctl status rke2-server

Per poter gestire il cluster Ku­ber­ne­tes dal tuo computer locale, copia il file kubeconfig:

sudo chmod 644 /etc/rancher/rke2/rke2.yaml
scp ubuntu@192.168.1.10:/etc/rancher/rke2/rke2.yaml ~/rke2-kubeconfig

Suc­ces­si­va­men­te, modifica l’IP del master nel file in modo che kubectl acceda cor­ret­ta­men­te al server:

sed -i 's/127.0.0.1:6443/192.168.1.10:6443/' ~/rke2-kubeconfig
export KUBECONFIG=~/rke2-kubeconfig

Con questo comando puoi ora ve­ri­fi­ca­re se il nodo master è rag­giun­gi­bi­le:

kubectl get nodes

Se il master viene vi­sua­liz­za­to, l’in­stal­la­zio­ne è stata com­ple­ta­ta cor­ret­ta­men­te e nel passo suc­ces­si­vo puoi ag­giun­ge­re i nodi worker.

Settimo passaggio: installa l’agente RKE2 sui nodi worker

Dopo che il nodo master è stato con­fi­gu­ra­to cor­ret­ta­men­te, puoi ora integrare i nodi worker nel cluster. A questo scopo installa su ogni worker l’agente RKE2 e collegalo al master.

Sul nodo master ti serve in­nan­zi­tut­to il node token, ne­ces­sa­rio per l’au­ten­ti­ca­zio­ne dei nodi worker presso il cluster:

sudo cat /var/lib/rancher/rke2/server/node-token

Annota il token. Ti servirà tra poco sui nodi worker.

Accedi tramite SSH a ciascun nodo worker:

ssh ubuntu@192.168.1.11

Scarica lo script di in­stal­la­zio­ne di RKE2 e installa l’agente con il seguente comando:

curl -sfL https://get.rke2.io | sudo INSTALL_RKE2_CHANNEL=v1.28 sh -

Suc­ces­si­va­men­te crea il file di con­fi­gu­ra­zio­ne per l’agente e inserisci l’IP del nodo master e il node token:

sudo mkdir -p /etc/rancher/rke2
cat <<EOF | sudo tee /etc/rancher/rke2/config.yaml
server: https://192.168.1.10
token: <INSERISCI_TOKEN_QUI>
EOF

Infine, abilita e avvia il servizio agente di RKE2:

sudo systemctl enable --now rke2-agent.service

Ripeti questa procedura per tutti i nodi worker nel cluster. Dopo alcuni minuti, puoi ve­ri­fi­ca­re sul master se i nodi worker sono stati collegati cor­ret­ta­men­te:

kubectl get nodes

Dovresti ora vedere tutti i nodi, il master e i nuovi worker aggiunti. Il tuo cluster è quindi completo e pronto per l’in­stal­la­zio­ne di plugin di rete, load balancer e altre com­po­nen­ti Ku­ber­ne­tes.

Ottavo passaggio: installa la CNI di rete e il load balancer

Dopo aver con­fi­gu­ra­to cor­ret­ta­men­te i nodi master e worker, hai bisogno di una container network interface (CNI) affinché i pod nel cluster possano co­mu­ni­ca­re tra loro, e di un load balancer per rendere rag­giun­gi­bi­li i servizi nella rete. In questa guida uti­liz­zia­mo Calico come CNI e MetalLB per la fun­zio­na­li­tà di load balancing di livello 2.

Calico gestisce le con­nes­sio­ni di rete tra i pod, regola l’as­se­gna­zio­ne degli IP e abilita op­zio­nal­men­te le regole di rete. Puoi in­stal­lar­lo con un semplice comando dal terminale:

kubectl apply -f https://docs.projectcalico.org/manifests/calico.yaml

Suc­ces­si­va­men­te verifica che tutti i pod di Calico siano stati avviati cor­ret­ta­men­te:

kubectl get pods -n kube-system

Tutti i pod do­vreb­be­ro mostrare lo stato Running o Completed. Se alcuni pod risultano ancora Pending, attendi qualche minuto: Calico ha bisogno di un po’ di tempo per di­stri­bui­re la con­fi­gu­ra­zio­ne di rete su tutti i nodi.

Ku­ber­ne­tes supporta na­ti­va­men­te il tipo di servizio load balancer, che richiede IP esterni. In un cluster auto-ospitato come su Proxmox, si usa MetalLB. Installa in­nan­zi­tut­to MetalLB:

kubectl apply -f https://raw.githubusercontent.com/metallb/metallb/v0.13.10/config/manifests/metallb-native.yaml

Crea quindi un pool di IP da cui MetalLB possa assegnare gli indirizzi IP ai servizi. Adatta l’in­ter­val­lo di IP alla tua rete locale:

cat <<EOF | kubectl apply -f -
apiVersion: metallb.io/v1beta1
kind: IPAddressPool
metadata:
name: my-ip-pool
namespace: metallb-system
spec:
addresses:
- 192.168.1.200-192.168.1.210
---
apiVersion: metallb.io/v1beta1
kind: L2Advertisement
metadata:
name: l2adv
namespace: metallb-system
spec: {}
EOF

Verifica anche in questo caso che i pod di MetalLB siano in ese­cu­zio­ne cor­ret­ta­men­te:

kubectl get pods -n metallb-system

Non appena tutti i pod hanno lo stato Running, la rete è con­fi­gu­ra­ta. Puoi ora usare servizi Ku­ber­ne­tes di tipo load balancer per rendere le ap­pli­ca­zio­ni rag­giun­gi­bi­li nella LAN. Il tuo cluster Ku­ber­ne­tes su Proxmox è così com­ple­ta­men­te con­fi­gu­ra­to e pronto per di­stri­bui­re le ap­pli­ca­zio­ni e gestire le risorse di rete.