# Creare un cluster Kubernetes su Proxmox: guida

La creazione di un cluster Kubernetes su Proxmox ti permette di gestire in un ambiente virtualizzato e auto-ospitato una **piattaforma performante di orchestrazione dei container**. Questa soluzione è particolarmente adatta ad ambienti di test, flussi di lavoro di sviluppo e CI o anche a scenari produttivi di piccole dimensioni. In questa guida scoprirai come configurare macchine virtuali su Proxmox e costruire su di esse un cluster Kubernetes stabile.

## Primo passaggio: verifica i prerequisiti

Prima di iniziare con la vera e propria configurazione del cluster Kubernetes, dovresti assicurarti che il tuo ambiente soddisfi tutti i prerequisiti tecnici. Una base pulita ti farà risparmiare molto tempo in seguito ed evita errori di configurazione.

Per prima cosa ti serve un’installazione funzionante di [Proxmox](https://www.ionos.it/digitalguide/server/know-how/proxmox/) VE. Per motivi di prestazioni si consiglia un’[installazione bare metal di Proxmox](https://www.ionos.it/digitalguide/server/configurazione/installazione-di-proxmox-su-bare-metal/). Devono essere disponibili sia l’**accesso web** tramite l’interfaccia Proxmox sia l’**accesso SSH** alla riga di comando. Tramite [SSH](https://www.ionos.it/digitalguide/server/tools-o-strumenti/ssh/) puoi eseguire comandi, caricare immagini e automatizzare configurazioni.

Per un [cluster Kubernetes](https://www.ionos.it/digitalguide/server/know-how/cluster-kubernetes/) stabile hai inoltre bisogno di diverse [macchine virtuali](https://www.ionos.it/digitalguide/server/know-how/macchine-virtuali/). Sono consigliati i seguenti [nodi Kubernetes](https://www.ionos.it/digitalguide/server/configurazione/nodo-di-kubernetes/):

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

In questo modo ottieni un certo grado di ridondanza e puoi eseguire [Kubernetes](https://www.ionos.it/digitalguide/server/know-how/che-cose-kubernetes/) così come previsto nei veri ambienti di produzione. Per scopi di test è però sufficiente anche una configurazione più piccola con un nodo master e uno worker.

Il tuo host Proxmox dovrebbe inoltre disporre di **un’interfaccia bridge funzionante**, che permetta alle macchine virtuali di accedere alla rete locale e, se necessario, a internet. Questo è importante affinché le VM possano in seguito scaricare aggiornamenti e installare i componenti di Kubernetes.

Consiglio Per gli ambienti produttivi è inoltre consigliabile configurare backup regolari delle macchine virtuali tramite un [server backup di Proxmox](https://www.ionos.it/digitalguide/server/configurazione/server-backup-di-proxmox/). In questo modo puoi ripristinare rapidamente i tuoi nodi Kubernetes, se necessario, e ridurre al minimo i tempi di inattività.

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

Le installazioni di Kubernetes sono più semplici da realizzare con le **immagini cloud**. Queste immagini di sistema operativo preconfigurate, perlopiù Ubuntu o Debian, sono ottimizzate per l’avvio automatico con `cloud-init`. In questo esempio utilizziamo un’immagine cloud Ubuntu 22.04 LTS, perché è stabile, ben documentata e ottimale per l’uso con Kubernetes.

Per prima cosa scarica l’ultima versione dell’immagine cloud di Ubuntu direttamente 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:

```bash
cd /var/lib/vz/template/iso
```

Scarica quindi l’immagine Ubuntu con il seguente comando:

```bash
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
```

N.B. In alternativa puoi prima scaricare l’immagine sul tuo computer locale e poi trasferirla sull’host Proxmox tramite `scp` (secure copy):

```bash
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à successivamente da template. A questo scopo crea innanzitutto **una VM vuota con un ID univoco**, ad esempio 9000, e assegnale le risorse hardware di base:

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

Ora importa l’immagine cloud precedentemente scaricata **come disco rigido virtuale nello spazio di archiviazione desiderato** (nel nostro esempio `local-lvm`):

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

Consiglio Se il tuo cluster Proxmox dispone di uno spazio di archiviazione distribuito, puoi in alternativa salvare l’immagine nell’archivio di Ceph. L’integrazione di [Ceph su Proxmox](https://www.ionos.it/digitalguide/server/configurazione/ceph-su-proxmox/) offre una soluzione di archiviazione ad alta disponibilità e scalabile per le tue VM Kubernetes.

Successivamente puoi collegare il disco importato alla VM e impostare il controller corretto. In questo modo l’immagine viene associata al controller SCSI virtuale della macchina virtuale:

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

Per impostare automaticamente in seguito, durante la clonazione delle VM, [indirizzi IP](https://www.ionos.it/digitalguide/server/know-how/cose-un-indirizzo-di-ip/), nomi host e chiavi SSH, hai bisogno di un’unità cloud init. Questa unità virtuale contiene i dati di configurazione applicati automaticamente all’avvio della VM. Aggiungi il drive cloud init e definisci l’ordine di boot con i seguenti comandi:

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

Attiva anche l’agente ospite di [QEMU](https://www.ionos.it/digitalguide/server/configurazione/qemu/), così che Proxmox possa in seguito **leggere le informazioni di stato dalla VM**, e configura una console seriale per avere accesso diretto alla console della VM in caso di emergenza:

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

Se tutto è configurato correttamente, puoi convertire la tua macchina virtuale in un cosiddetto 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 Kubernetes.

```bash
qm template 9000
```

Dopo questo passaggio, il template Ubuntu è pronto e può essere utilizzato come base per i tuoi nodi Kubernetes master e worker.

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

Nel terzo passaggio crei, a partire dal template precedentemente configurato, le macchine virtuali che in seguito **funzioneranno come nodi master e worker del tuo cluster Kubernetes**. Ciascuna di queste VM riceve un proprio indirizzo IP, un nome host univoco e una chiave SSH per l’accesso sicuro. Proxmox gestisce automaticamente la configurazione di base tramite `cloud-init`, così non devi più effettuare alcuna configurazione manuale all’interno delle macchine virtuali.

Clona innanzitutto il template creato in precedenza (in questo esempio con l’ID 9000) e crea da esso **tre macchine virtuali**: una per il nodo master e due per i corrispondenti nodi worker. In questo caso puoi adattare in modo personalizzato [CPU](https://www.ionos.it/digitalguide/server/know-how/cpu/) e [RAM](https://www.ionos.it/digitalguide/server/know-how/che-cose-la-memoria-ad-accesso-casuale-ram/):

```bash
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
```

Successivamente definisci tramite `cloud-init` le impostazioni di rete di base, il nome host e la chiave SSH. Puoi assegnare indirizzi IP fissi oppure utilizzare [DHCP](https://www.ionos.it/digitalguide/server/configurazione/dhcp-una-panoramica-del-protocollo-client-server/). In questo esempio vengono utilizzati indirizzi statici:

```bash
# 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
```

N.B. Adatta gli indirizzi IP di esempio utilizzati qui alla tua rete. Usa valori dell’intervallo IP del tuo router e assicurati che ogni VM riceva un indirizzo univoco che non sia ancora stato assegnato.

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

```bash
qm start 101
qm start 102
qm start 103
```

Attendi qualche istante finché i sistemi non sono completamente avviati, quindi **verifica la connessione via SSH**. Se tutto funziona, puoi ad esempio accedere al nodo master con il seguente comando:

```none
ssh ubuntu@192.168.1.10
```

## Quarto passaggio: aggiungi la configurazione di base su tutte le macchine virtuali

Prima di installare Kubernetes sulle VM, dovresti applicare alcune impostazioni a livello di sistema, necessarie per un funzionamento stabile. Tra queste rientrano la disattivazione dello swap, la regolazione dei parametri del [kernel](https://www.ionos.it/digitalguide/server/know-how/cose-un-kernel/) per rete e inoltro dell’indirizzo IP, oltre alla sincronizzazione dell’ora di sistema. Queste misure garantiscono che Kubernetes possa operare correttamente e che le funzioni di rete all’interno dei container funzionino in modo affidabile.

Per prima cosa disattiva lo swap su tutti i nodi, poiché Kubernetes lo **richiede per la logica dello scheduler**. Inoltre, rimuovi la voce corrispondente in `/etc/fstab`, in modo che lo swap non venga riattivato dopo un riavvio:

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

Successivamente configuri i parametri del kernel per assicurarti che i pacchetti di rete tra container e nodi possano essere elaborati correttamente:

```bash
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 importante è la sincronizzazione dell’ora di sistema, in modo che certificati e componenti del cluster non causino problemi per via di orari non allineati. A questo scopo puoi installare e avviare `chrony`:

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

Infine, è consigliabile installare alcuni **strumenti di base** che saranno utili nei passaggi successivi:

```bash
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 è disattivato, le impostazioni di rete sono configurate correttamente e l’ora è sincronizzata. Le tue VM sono ora pronte per l’installazione di Kubernetes e la creazione del tuo cluster.

## Quinto passaggio: scegli la distribuzione Kubernetes

Prima di iniziare con la vera e propria installazione di Kubernetes, dovresti scegliere una **distribuzione adatta**. In base alle tue esigenze puoi optare tra due varianti consigliate:

- **RKE2 (Rancher Kubernetes Engine 2)**: RKE2 è una distribuzione Kubernetes stabile e pronta per l’ambiente di produzione, sviluppata da Rancher. È particolarmente adatta se in seguito vorresti utilizzare una gestione grafica tramite Rancher o se prevedi un cluster con più nodi di control plane.
- **k3s**: [k3s](https://www.ionos.it/digitalguide/server/know-how/che-cose-k3s/) è una distribuzione Kubernetes leggera, adatta ad ambienti di test, home lab o sistemi con risorse limitate. È molto semplice da installare e richiede meno memoria e CPU.

Per la creazione di un **cluster Kubernetes robusto su Proxmox**, che possa essere utilizzato anche in uno scenario vicino alla produzione, **si consiglia RKE2**. Se invece desideri configurare rapidamente un piccolo cluster di test o sviluppo, k3s è l’alternativa più pratica. Nel resto di questa guida verrà utilizzato RKE2.

## Sesto passaggio: installa RKE2 sul nodo master

Dopo aver completato la configurazione di base delle macchine virtuali puoi iniziare con **l’installazione di RKE2 sul nodo master**. Per farlo, accedi via SSH al nodo master:

```bash
ssh ubuntu@192.168.1.10
```

Ora scarica lo script di installazione di RKE2 ed eseguilo. Puoi facoltativamente specificare un canale con la versione desiderata:

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

Dopo l’installazione attiva il servizio server RKE2 e avvialo immediatamente:

```bash
sudo systemctl enable --now rke2-server.service
```

Verifica con il seguente comando che il server RKE2 sia in esecuzione correttamente:

```bash
sudo systemctl status rke2-server
```

Per poter gestire il cluster Kubernetes dal tuo computer locale, copia il file `kubeconfig`:

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

Successivamente, modifica l’IP del master nel file in modo che `kubectl` acceda correttamente al server:

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

Con questo comando puoi ora verificare se il nodo master è raggiungibile:

```bash
kubectl get nodes
```

Se il master viene visualizzato, l’installazione è stata completata correttamente e nel passo successivo puoi aggiungere i nodi worker.

## Settimo passaggio: installa l’agente RKE2 sui nodi worker

Dopo che il nodo master è stato configurato correttamente, 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 innanzitutto il **node token**, necessario per l’autenticazione dei nodi worker presso il cluster:

```bash
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:

```bash
ssh ubuntu@192.168.1.11
```

Scarica lo script di installazione di RKE2 e installa l’agente con il seguente comando:

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

Successivamente crea il file di configurazione per l’agente e inserisci l’IP del nodo master e il node token:

```bash
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:

```bash
sudo systemctl enable --now rke2-agent.service
```

**Ripeti questa procedura** per tutti i nodi worker nel cluster. Dopo alcuni minuti, puoi verificare sul master se i nodi worker sono stati collegati correttamente:

```bash
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’installazione di plugin di rete, load balancer e altre componenti Kubernetes.

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

Dopo aver configurato correttamente i nodi master e worker, hai bisogno di una **container network interface (CNI)** affinché i pod nel cluster possano comunicare tra loro, e di un **load balancer** per rendere raggiungibili i servizi nella rete. In questa guida utilizziamo Calico come CNI e MetalLB per la funzionalità di [load balancing](https://www.ionos.it/digitalguide/server/know-how/load-balancer-bilanciamento-del-carico-nel-server/) di livello 2.

**Calico gestisce le connessioni di rete tra i pod**, regola l’assegnazione degli IP e abilita opzionalmente le regole di rete. Puoi installarlo con un semplice comando dal terminale:

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

Successivamente verifica che tutti i pod di Calico siano stati avviati correttamente:

```bash
kubectl get pods -n kube-system
```

Tutti i pod dovrebbero mostrare lo stato `Running` o `Completed`. Se alcuni pod risultano ancora `Pending`, attendi qualche minuto: Calico ha bisogno di un po’ di tempo per distribuire la configurazione di rete su tutti i nodi.

Kubernetes supporta nativamente il **tipo di servizio load balancer**, che richiede IP esterni. In un cluster auto-ospitato come su Proxmox, si usa MetalLB. Installa innanzitutto MetalLB:

```bash
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’intervallo di IP alla tua rete locale:

```bash
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 esecuzione correttamente:

```bash
kubectl get pods -n metallb-system
```

Non appena tutti i pod hanno lo stato `Running`, la rete è configurata. Puoi ora usare servizi Kubernetes di tipo load balancer per rendere le applicazioni raggiungibili nella LAN. Il tuo cluster Kubernetes su Proxmox è così completamente configurato e pronto per distribuire le applicazioni e gestire le risorse di rete.


This is a markdown version of: [https://www.ionos.it/digitalguide/server/configurazione/cluster-kubernetes-su-proxmox/](https://www.ionos.it/digitalguide/server/configurazione/cluster-kubernetes-su-proxmox/) for AI/LLM consumption.