Homelab Rebuild 2026 — Costruire il cluster Proxmox e fare provisioning con Terraform

🌐 Anche in: English · Deutsch · Français · Español · Português · Nederlands · Polski
Nel post precedente ho presentato il piano per ricostruire il mio homelab come un piccolo datacenter in stile enterprise: cinque pilastri, otto milestone, un post per milestone. La milestone 1 è la base su cui poggia tutto il resto — tre macchine fisiche trasformate in un unico cluster Proxmox VE, più il modulo Terraform che d’ora in poi fa il provisioning di ogni VM al di sopra. Questo post copre entrambe le cose. Avviso onesto: tutto questo progetto è decisamente un lavoro in corso. Niente qui è “finito” o definitivo — è beta nel migliore dei casi, e continua a cambiare man mano che procedo. Considera questo post un’istantanea di com’erano le cose quando l’ho scritto, non un progetto completato.
Indice
🎯 Obiettivo di questa milestone
Due cose dovevano essere vere prima che potessi toccare Active Directory, GitLab o Kubernetes:
- Tre macchine HP separate dovevano diventare un unico cluster Proxmox VE, così che le VM si possano gestire, migrare e salvare da un’unica console.
- Nessuna VM doveva mai più nascere a forza di clic. Ogni VM — dal domain controller al control plane di Kubernetes — viene creata da
terraform apply, non da un wizard nell’interfaccia di Proxmox.
Tutto quello che segue riflette il cluster così come gira oggi — ho preso i valori reali direttamente dall’API di Proxmox invece di affidarmi agli appunti del giorno dell’installazione.
🖥️ Hardware
Tre macchine HP, volutamente non identiche — è hardware riciclato, non un set coordinato:
| Host | RAM | Storage | IP di gestione |
|---|---|---|---|
| HP1 | 64 GB | SSD OS da 512 GB + SSD da 2 TB | 192.168.10.x |
| HP2 | 32 GB | SSD OS da 512 GB + SSD da 2 TB | 192.168.10.x |
| HP3 | 32 GB | SSD OS da 512 GB + 3×2 TB (ZFS RAIDZ1) | 192.168.10.x |
💽 Installare Proxmox VE
Niente di speciale nell’installazione in sé: ISO di Proxmox VE 9.2, scritta su una chiavetta USB con Rufus, una chiavetta per macchina, avvio, installazione, ripetere tre volte. Niente virtual media remoti, niente PXE — per tre macchine sulla stessa scrivania, una chiavetta USB resta la strada più veloce da zero a un hypervisor funzionante.
Durante l’installazione ogni nodo ha ricevuto un IP statico sulla rete di gestione 192.168.10.x/24 (.30, .40, .50 per HP1–HP3), che fa anche da rete su cui vivono il cluster e tutte le VM — più avanti parlo di questo compromesso.
Un passo post-installazione su tutti e tre: cambiare i repository dei pacchetti. Proxmox di default punta al repository Enterprise, che richiede un abbonamento a pagamento per scaricare davvero gli aggiornamenti. Seguendo i passi documentati da Proxmox stesso, ho disattivato il repo Enterprise e ho fatto puntare ogni nodo al No-Subscription Repository — va bene per test e uso non di produzione, che è esattamente ciò che è un homelab, solo senza la stessa validazione che riceve il repo Enterprise:
# /etc/apt/sources.list.d/proxmox.sources
Types: deb
URIs: http://download.proxmox.com/debian/pve
Suites: trixie
Components: pve-no-subscription
Signed-By: /usr/share/keyrings/proxmox-archive-keyring.gpg
Con questo a posto, il solito giro su tutti e tre i nodi prima di fare qualsiasi altra cosa:
apt-get update
apt-get upgrade
apt-get dist-upgrade
🌐 Rete
Ogni nodo ha una sola scheda di rete in bridge come vmbr0 (Linux bridge, STP spento), a cui si collega più avanti il network_device di ogni VM. Sulle schede madri esiste una seconda porta di rete integrata, ma per ora resta inutilizzata — candidata per una rete dedicata allo storage o a corosync in futuro, ma non qualcosa di cui un cluster homelab a 3 nodi abbia bisogno dal primo giorno.
Questa è anche l’unica semplificazione deliberata che vale la pena sottolineare: corosync (il protocollo di heartbeat/quorum del cluster) gira sulla stessa rete del traffico di gestione e delle VM, usando un singolo ring:
ring0_addr: HP1 = 192.168.10.x
ring0_addr: HP2 = 192.168.10.x
ring0_addr: HP3 = 192.168.10.x
In un cluster di produzione isoleresti corosync su una sua VLAN o sue schede di rete, così che una rete di gestione saturata non possa causare perdite di quorum spurie. Per tre nodi su una rete domestica senza altro traffico in competizione per la banda, quel rischio è accettabile — è nella lista delle cose da rivedere se tutto questo dovesse mai crescere oltre un homelab. Se mai dovessi incappare in perdite di quorum spurie, RackNotes ha una guida approfondita su calcolo dei voti, modalità di guasto di Corosync, QDevice e percorsi di ripristino: perdita di quorum nel cluster Proxmox.
🔗 Formare il cluster
Il classico flusso pvecm: creare il cluster su HP1, poi far unire HP2 e HP3. Con tre membri votanti il cluster tollera esattamente un nodo offline (2 voti su 3) prima di perdere il quorum — il setup HA minimo sensato, e il motivo per cui ho scelto tre nodi invece di due fin dall’inizio. Interrogare il cluster oggi conferma che il percorso felice ha tenuto:
$ pvecm status
Cluster name: homelab
Quorate: Yes
Nodes: 3
Nodeid Ip Name
1 192.168.10.x HP1 (local)
2 192.168.10.x HP2
3 192.168.10.x HP3
🗄️ Layout dello storage
È qui che i tre nodi smettono di essere identici. Il secondo disco di ogni nodo (o i dischi, per HP3) è configurato in modo diverso di proposito:
- HP1 & HP2: l’SSD aggiuntivo da 2 TB è aggiunto come semplice storage a directory (
data/data-hp2) — niente ZFS, niente RAID, solo un filesystem per dischi delle VM, ISO e backup. Un solo SSD, niente con cui fare mirror, quindi vince l’opzione più semplice. - HP3: tre dischi da 2 TB vanno in un pool ZFS in RAIDZ1 (
data-hp3), che dà poco meno di 4 TB utilizzabili con tolleranza al guasto di un disco. È il nodo destinato a tutto ciò che non voglio perdere per un singolo disco morto — pensa alle repliche di Longhorn o ai dati di MinIO quando arriverà Kubernetes.
Ogni nodo mantiene anche gli storage di default local (filesystem root) e local-lvm (LVM-thin sull’SSD del sistema operativo) creati dall’installer, usati per il sistema operativo stesso e come riserva.
🧱 Da ClickOps a Infrastructure as Code
Con il cluster su, il passo successivo allettante è cliccare sette volte su “Create VM” nell’interfaccia di Proxmox. L’ho fatto esattamente così nella versione precedente di questo homelab, e ogni VM è venuta fuori leggermente diversa — un’impostazione cloud-init dimenticata qui, un IP statico digitato a mano là, nessuna traccia di cosa avessi fatto davvero sei mesi dopo. Non questa volta: ogni VM di questa ricostruzione è definita una sola volta, in Terraform, e riproducibile da un cluster pulito.
⚙️ Il modulo Terraform
Il modulo vive in 01_terraform/ nel repository del progetto e usa il provider bpg/proxmox. Invece di montare una ISO di Ubuntu Server e cliccare attraverso l’installer, ogni VM viene clonata da una cloud image di Ubuntu 26.04 e configurata interamente tramite cloud-init — IP statico, DNS, chiave SSH, tutto — quindi non c’è nessun passo di installazione interattivo da nessuna parte nella pipeline:
resource "proxmox_download_file" "ubuntu_cloud_image" {
content_type = "iso"
datastore_id = var.image_datastore_id
node_name = var.proxmox_node
url = var.ubuntu_cloud_image_url
file_name = "noble-server-cloudimg-amd64.img"
overwrite = false
}
resource "proxmox_virtual_environment_vm" "vm" {
for_each = local.vms
name = each.key
tags = ["terraform", "rebuild-2026"]
node_name = var.proxmox_node
vm_id = each.value.vmid
disk {
datastore_id = var.vm_datastore_id
file_id = proxmox_download_file.ubuntu_cloud_image.id
interface = "scsi0"
size = each.value.disk_gb
}
initialization {
ip_config {
ipv4 {
address = "${each.value.ip}/${var.network_prefix}"
gateway = var.network_gateway
}
}
user_account {
username = var.vm_username
keys = var.ssh_public_keys
}
}
}
Tutte e sette le VM — una per ruolo per questa milestone — sono dichiarate in una singola mappa locals.vms, così aggiungere un’ottava VM più avanti è un diff di cinque righe, non un blocco di risorse copiato e incollato:
| Nome | Ruolo | IP | RAM | Disco |
|---|---|---|---|---|
| HP1-dc01 | AD / DNS / Root CA | 192.168.10.x | 4 GB | 60 GB |
| HP1-gitlab01 | GitLab / Container Registry | 192.168.10.x | 8 GB | 120 GB |
| HP1-seed01 | VM di sviluppo (Ansible, kubectl, strumenti) | 192.168.10.x | 4 GB | 60 GB |
| HP1-vault01 | Gestione dei secret (fase 2) | 192.168.10.x | 2 GB | 40 GB |
| HP1-icinga01 | Monitoraggio | 192.168.10.x | 4 GB | 60 GB |
| HP1-k8s-cp01 | Control plane RKE2 | 192.168.10.x | 8 GB | 80 GB |
| HP1-k8s-cp02 | Control plane RKE2 | 192.168.10.x | 8 GB | 80 GB |
Gli ID delle VM seguono 100 + <last IP octet> (131–137) — Proxmox richiede ID ≥ 100, e in questo modo ID e indirizzo restano facili da associare a colpo d’occhio, senza una tabella di lookup separata.
▶️ Il rollout
L’intero rollout sono tre comandi, una volta che un token API di Proxmox e una chiave SSH sono a posto:
cp terraform.tfvars.example terraform.tfvars
# edit terraform.tfvars: API URL, API token, node name, SSH key
terraform init
terraform plan
terraform apply
Un paio di minuti dopo, tutte e sette le VM esistono, si avviano e rispondono sugli IP assegnati — e Terraform ti dice esattamente quale è quale:
Outputs:
vm_ids = {
"HP1-dc01" = 131
"HP1-gitlab01" = 132
"HP1-icinga01" = 135
"HP1-k8s-cp01" = 136
"HP1-k8s-cp02" = 137
"HP1-seed01" = 133
"HP1-vault01" = 134
}
vm_ips = {
"HP1-dc01" = "192.168.10.x"
"HP1-gitlab01" = "192.168.10.x"
...
}
🧩 Alcune cose da segnalare
- Cloud image, non ISO. La ISO di Ubuntu sullo storage locale di HP1 non viene usata da questo modulo di proposito — clonare una cloud image e configurarla via cloud-init è più veloce e completamente automatico. La ISO resta lì solo per la rara installazione manuale.
ignore_changessulfile_iddel disco. Senza, Terraform vuole reimportare l’immagine base a ogni plan, dato che l’ID del file scaricato non è pensato per essere riconciliato dopo il clone iniziale.- I secret non lasciano mai il repository interno.
terraform.tfvarscontiene il vero token API e la chiave SSH ed è in gitignore; un hook pre-push impedisce attivamente che arrivi mai al mirror pubblico di questo progetto su GitHub, in aggiunta al gitignore. - Lo state è locale, e va bene così. Un operatore, un portatile che esegue
apply— un backend remoto risolverebbe un problema che non ho ancora.
Per una guida tecnica più approfondita del modulo — architettura, ogni variabile, l’inventario completo delle VM e una lista sempre aggiornata di lezioni imparate — vedi 01_terraform/docs/ nel repository (in inglese, tedesco e francese).
⚠️ Questo intero progetto — compreso il codice Terraform mostrato qui sotto — è un lavoro perennemente in corso. Funziona, fa quello che dice, ma è ancora beta e viene rimaneggiato di continuo. Non considerare niente di tutto questo come finito o stabile.
📊 Il punto cieco del ballooning su Windows
HP1-dc01 viene creato da questo modulo come ogni altra VM, ma non resta Ubuntu a lungo — subito dopo viene convertito in Windows Server, perché è quello che serve ad Active Directory. Nel momento in cui è successo, il suo grafico della RAM nel riepilogo di Proxmox si è appiattito al 100% dei 4 GB assegnati, per quanto la VM fosse in realtà inattiva.
La causa: Proxmox non misura direttamente l’uso di memoria del guest. Lo rilegge dal dispositivo balloon virtuale di QEMU, che riporta numeri reali solo se dentro il guest gira un driver che lo alimenta. Sulle VM Linux di questo cluster, quello arriva insieme a qemu-guest-agent — già trattato nella correzione del guest agent qui sopra. Windows Server non ha nulla di equivalente integrato, quindi senza software aggiuntivo il dispositivo balloon non ha niente da riportare, e Proxmox mostra semplicemente la VM inchiodata alla sua allocazione completa.
La soluzione è stata un secondo CD-ROM virtuale: montare la ISO dei driver virtio-win e installare da lì il VirtIO Balloon Driver tramite Gestione dispositivi. È lo stesso pacchetto di driver che contiene anche l’equivalente Windows del guest agent — una volta installato, il grafico del riepilogo ha iniziato a seguire la reale pressione sulla memoria invece di una linea piatta al soffitto. Di come trasformare questa VM in un vero domain controller parlo nel prossimo post.
🔜 Cosa viene dopo
Con un cluster a 3 nodi con quorum e un modo ripetibile per tirare su VM, la milestone 2 comincia a trasformare HP1-dc01 in un vero domain controller: Active Directory, DNS e la Root CA offline di cui prima o poi si fiderà tutto il resto di questo homelab. Questo è il prossimo post.

📚 Altro in questa serie: Homelab Rebuild 2026
- Homelab Rebuild 2026 — Dall’homelab a un mini datacenter
- Homelab Rebuild 2026 — Active Directory, il riciclaggio di Pi-hole e una lettera di unità che si rifiuta di esistere
- Homelab Rebuild 2026 — GitLab, una seed VM e la quiete prima della tempesta Kubernetes
- Homelab Rebuild 2026: Aspettare e vedere - un crash del server, un advisory senza uscita e il mio nuovo sospettato numero uno
