Maintenance script: Aggiunta documentazione tecnica dettagliata del deploy VM

2026-03-29T18:57:47Z

Aggiunta documentazione tecnica dettagliata del deploy VM

← Versione meno recente		Versione delle 18:57, 29 mar 2026
Riga 202:		Riga 202:

	Funzioni principali:		Funzioni principali:
	* <code>syncNetworkFields()</code>		* <code>syncNetworkFields()</code>: disabilita i campi IP/gateway/CIDR quando la rete e DHCP
	disabilita i campi IP/gateway/CIDR quando la rete e DHCP		* <code>renderJobs()</code>: mostra i job recenti con stato, timing e output
	* <code>renderJobs()</code>		* <code>loadVlans()</code>: chiama <code>/api/network/vlans</code>
	mostra i job recenti con stato, timing e output		* <code>loadBridges()</code>: chiama <code>/api/network/bridges</code>
	* <code>loadVlans()</code>		* <code>loadFreeVmid()</code>: chiama <code>/api/proxmox/free-vmid?start=100</code>
	chiama <code>/api/network/vlans</code>		* <code>validateNetwork()</code>: chiama <code>/api/network/validate</code> prima del submit
	* <code>loadBridges()</code>		* <code>loadJobs()</code>: ricarica i job recenti
	chiama <code>/api/network/bridges</code>		* submit handler della form: costruisce il payload JSON e lo invia a <code>/api/jobs/create-vm</code>
	* <code>loadFreeVmid()</code>
	chiama <code>/api/proxmox/free-vmid?start=100</code>
	* <code>validateNetwork()</code>
	chiama <code>/api/network/validate</code> prima del submit
	* <code>loadJobs()</code>
	ricarica i job recenti
	* submit handler della form
	costruisce il payload JSON e lo invia a <code>/api/jobs/create-vm</code>

	Traduzione pratica:		Traduzione pratica:
Riga 281:		Riga 273:

	Funzioni:		Funzioni:
	* <code>wait_for_guest_agent()</code>		* <code>wait_for_guest_agent()</code>: esegue poll su <code>qm agent VMID ping</code>
	esegue poll su <code>qm agent VMID ping</code>		* <code>guest_exec()</code>: esegue un comando dentro la VM via guest agent e aspetta l'exit status
	* <code>guest_exec()</code>
	esegue un comando dentro la VM via guest agent e aspetta l'exit status

	Uso concreto nel progetto:		Uso concreto nel progetto:

Maintenance script: Aggiunta documentazione tecnica dettagliata del deploy VM

2026-03-29T18:55:31Z

Aggiunta documentazione tecnica dettagliata del deploy VM

← Versione meno recente		Versione delle 18:55, 29 mar 2026
Riga 29:		Riga 29:

	=== Lettura riga per riga ===		=== Lettura riga per riga ===
	<~~syntaxhighlight lang="python"~~>		<pre>
	#!/usr/bin/env python3		#!/usr/bin/env python3
	import os		import os
Riga 36:		Riga 36:

	from pyinfra.operations import server		from pyinfra.operations import server
	</~~syntaxhighlight~~>		</pre>

	Spiegazione:		Spiegazione:
Riga 43:		Riga 43:
	* import dell'operation <code>server.shell</code>		* import dell'operation <code>server.shell</code>

	<~~syntaxhighlight lang="python"~~>		<pre>
	BASE_DIR = Path(__file__).resolve().parents[1]		BASE_DIR = Path(__file__).resolve().parents[1]
	python_bin = os.environ.get("PYTHON_BIN", str(BASE_DIR / "venv" / "bin" / "python"))		python_bin = os.environ.get("PYTHON_BIN", str(BASE_DIR / "venv" / "bin" / "python"))
	helper = BASE_DIR / "lib" / "proxmox_ssh.py"		helper = BASE_DIR / "lib" / "proxmox_ssh.py"
	cmd = f"{shlex.quote(python_bin)} {shlex.quote(str(helper))}"		cmd = f"{shlex.quote(python_bin)} {shlex.quote(str(helper))}"
	</~~syntaxhighlight~~>		</pre>

	Spiegazione:		Spiegazione:
Riga 56:		Riga 56:
	* costruisce un comando shell sicuro con quoting		* costruisce un comando shell sicuro con quoting

	<~~syntaxhighlight lang="python"~~>		<pre>
	server.shell(		server.shell(
	name=f"Create Proxmox VM {os.environ.get('VM_NAME', '')}",		name=f"Create Proxmox VM {os.environ.get('VM_NAME', '')}",
	commands=[cmd],		commands=[cmd],
	)		)
	</~~syntaxhighlight~~>		</pre>

	Spiegazione:		Spiegazione:
Riga 173:		Riga 173:

	Comando usato:		Comando usato:
	<~~syntaxhighlight lang="bash"~~>		<pre>
	pyinfra @local deploys/create_vm.py -y		pyinfra @local deploys/create_vm.py -y
	</~~syntaxhighlight~~>		</pre>

	=== Blocco 7: interfaccia HTML ===		=== Blocco 7: interfaccia HTML ===
Riga 330:		Riga 330:

	Prima di creare la VM, il file esegue:		Prima di creare la VM, il file esegue:
	<~~syntaxhighlight lang="bash"~~>		<pre>
	qm config <VMID>		qm config <VMID>
	</~~syntaxhighlight~~>		</pre>

	Se il comando funziona, il VMID esiste gia e il job viene fermato.		Se il comando funziona, il VMID esiste gia e il job viene fermato.

Maintenance script: Aggiunta documentazione tecnica dettagliata del deploy VM

2026-03-29T18:51:30Z

Aggiunta documentazione tecnica dettagliata del deploy VM

Nuova pagina

__NOTOC__
= Pyinfra/Implementazione deploy VM linea per linea =

Questa pagina documenta l'implementazione del deploy automatico di macchine virtuali pubblicata su <code>bot.gazzi.net/pyinfra/</code>.

Obiettivo della pagina:
* far capire il flusso a una persona umana
* spiegare il ruolo di ogni file
* descrivere il codice in ordine logico
* collegare il comportamento osservabile alle righe principali dell'implementazione

Non vengono riportati segreti runtime.

== Vista d'insieme ==
I file che contano sono tre:
* <code>app.py</code>: web UI, login LDAP, API, job queue
* <code>deploys/create_vm.py</code>: entry point pyinfra
* <code>lib/proxmox_ssh.py</code>: logica concreta di creazione VM su Proxmox

Sequenza completa:
# l'utente invia la form
# <code>app.py</code> valida il payload e crea il job
# il job esegue <code>pyinfra @local deploys/create_vm.py -y</code>
# <code>create_vm.py</code> richiama <code>lib/proxmox_ssh.py</code>
# <code>proxmox_ssh.py</code> esegue i comandi <code>qm</code>, gestisce cloud-init e cleanup

== File 1: deploys/create_vm.py ==
Questo file e volutamente piccolo. Il suo scopo non e contenere logica complessa, ma fare da ponte tra pyinfra e l'helper specializzato.

=== Lettura riga per riga ===
<syntaxhighlight lang="python">
#!/usr/bin/env python3
import os
import shlex
from pathlib import Path

from pyinfra.operations import server
</syntaxhighlight>

Spiegazione:
* shebang Python
* import minimi
* import dell'operation <code>server.shell</code>

<syntaxhighlight lang="python">
BASE_DIR = Path(__file__).resolve().parents[1]
python_bin = os.environ.get("PYTHON_BIN", str(BASE_DIR / "venv" / "bin" / "python"))
helper = BASE_DIR / "lib" / "proxmox_ssh.py"
cmd = f"{shlex.quote(python_bin)} {shlex.quote(str(helper))}"
</syntaxhighlight>

Spiegazione:
* calcola la base del progetto
* legge il Python del virtualenv da variabile ambiente oppure usa il default
* individua l'helper vero da eseguire
* costruisce un comando shell sicuro con quoting

<syntaxhighlight lang="python">
server.shell(
name=f"Create Proxmox VM {os.environ.get('VM_NAME', '')}",
commands=[cmd],
)
</syntaxhighlight>

Spiegazione:
* pyinfra vede una singola operation
* il nome dell'operation include il nome VM per leggibilita
* l'operation esegue localmente il comando helper

Idea pratica:
* pyinfra orchestra
* l'helper specializzato realizza la logica

== File 2: app.py ==
Questo file ha quattro responsabilita:
* leggere la configurazione
* fare autenticazione LDAP
* servire UI e API
* creare e monitorare i job

=== Blocco 1: costanti e caricamento environment ==
Righe utili: <code>16-64</code>

Che cosa succede:
* viene definita la base del progetto
* viene caricato <code>/etc/pyinfra-webui/pyinfra-webui.env</code>
* viene inizializzata la directory stato
* vengono lette le variabili principali di app, LDAP e Proxmox
* Flask viene configurato con secret key e cookie di sessione
* vengono preparate strutture dati e lock per i job

Perche e importante:
* tutta la logica runtime dipende da questo blocco
* separa configurazione e codice
* permette di non versionare i segreti

=== Blocco 2: autenticazione e URL dietro proxy ==
Righe utili: <code>67-140</code>

Funzioni:
* <code>now_iso()</code>: timestamp uniforme dei job
* <code>require_token()</code>: token opzionale per API
* <code>forwarded_prefix()</code> e <code>url_with_prefix()</code>: supporto a <code>/pyinfra</code> dietro reverse proxy
* <code>is_authenticated()</code> e <code>require_login()</code>: controllo sessione
* <code>validate_username()</code>: sanifica lo username LDAP
* <code>ldap_authenticate()</code>: bind LDAP con template DN

Traduzione umana:
* l'app sa stare dietro Nginx senza rompere i path
* l'utente deve autenticarsi via LDAP
* eventuali API possono richiedere un token aggiuntivo se configurato

=== Blocco 3: lettura dati da Proxmox ==
Righe utili: <code>121-189</code>

Qui trovi:
* <code>proxmox_run()</code>: apre una connessione SSH a Proxmox per eseguire comandi
* <code>discover_vlans()</code>: parsifica l'output di <code>bridge vlan show</code>
* <code>discover_bridges()</code>: legge i bridge con <code>ip -o link show type bridge</code>
* <code>discover_used_vmids()</code>: legge i VMID esistenti con <code>qm list</code>
* <code>first_free_vmid()</code>: cerca il primo VMID libero da un valore iniziale

Perche serve:
* la UI non usa valori statici
* l'utente puo interrogare Proxmox prima del submit

=== Blocco 4: validazione input ==
Righe utili: <code>192-263</code>

Qui l'app controlla:
* range di interi
* formato nome VM
* formato utente Linux
* lunghezza minima password
* modalita rete
* formato bridge
* VLAN opzionale
* IP, gateway e CIDR se la rete e statica

Risultato:
* l'input viene normalizzato in <code>spec</code>
* i segreti vengono separati in <code>secrets</code>

Questa separazione e importante:
* <code>spec</code> puo essere esposto nel job
* <code>secrets</code> va trattato con piu cautela

=== Blocco 5: costruzione environment job ==
Righe utili: <code>266-290</code>

<code>build_job_env()</code> converte il dizionario del job in variabili ambiente da passare al runner.

Questo blocco e il ponte tra:
* input raccolto dalla UI
* variabili ambiente lette da <code>proxmox_ssh.py</code>

Esempi:
* <code>spec["vmid"]</code> diventa <code>VM_ID</code>
* <code>spec["bridge"]</code> diventa <code>VM_BRIDGE</code>
* la password admin diventa <code>VM_ADMIN_PASSWORD</code>

=== Blocco 6: job queue e logging ==
Righe utili: <code>293-347</code>

Componenti:
* <code>append_job()</code>: inserisce il job nelle strutture in memoria
* <code>write_job_log()</code>: salva il log su file in <code>APP_STATE_DIR</code>
* <code>run_job()</code>: lancia pyinfra in subprocess
* <code>create_job()</code>: impedisce job concorrenti e avvia il thread

Punto chiave:
* <code>active_job_lock</code> fa da semaforo per evitare due creazioni VM contemporanee

Comando usato:
<syntaxhighlight lang="bash">
pyinfra @local deploys/create_vm.py -y
</syntaxhighlight>

=== Blocco 7: interfaccia HTML ===
Righe utili: <code>350-560</code>

La parte HTML/CSS contiene:
* layout pagina
* campi del form
* sezione job recenti

Campi operativi importanti:
* VMID
* nome VM
* utente sudo
* password sudo
* CPU, RAM, disco
* rete, bridge, VLAN
* gateway, CIDR, IP statico
* checkbox avvio automatico

Nota:
* le righe di stile puro servono a presentazione e leggibilita, non alla logica di deploy

=== Blocco 8: JavaScript della UI ===
Righe utili: <code>563-726</code>

Funzioni principali:
* <code>syncNetworkFields()</code>
disabilita i campi IP/gateway/CIDR quando la rete e DHCP
* <code>renderJobs()</code>
mostra i job recenti con stato, timing e output
* <code>loadVlans()</code>
chiama <code>/api/network/vlans</code>
* <code>loadBridges()</code>
chiama <code>/api/network/bridges</code>
* <code>loadFreeVmid()</code>
chiama <code>/api/proxmox/free-vmid?start=100</code>
* <code>validateNetwork()</code>
chiama <code>/api/network/validate</code> prima del submit
* <code>loadJobs()</code>
ricarica i job recenti
* submit handler della form
costruisce il payload JSON e lo invia a <code>/api/jobs/create-vm</code>

Traduzione pratica:
* il browser non parla direttamente con Proxmox
* parla solo con le API dell'app
* la UI ferma l'utente prima se bridge/VLAN non sono validi

=== Blocco 9: login e API backend ===
Righe utili: <code>733-938</code>

Route principali:
* <code>/api/health</code>
* <code>/login</code>
* <code>/logout</code>
* <code>/api/jobs</code>
* <code>/api/network/vlans</code>
* <code>/api/network/bridges</code>
* <code>/api/network/validate</code>
* <code>/api/proxmox/free-vmid</code>
* <code>/api/jobs/create-vm</code>

Punto critico:
* <code>/api/jobs/create-vm</code> fa il passaggio da richiesta web a job reale

Il flusso della route finale e:
# richiede login
# opzionalmente richiede token
# legge il JSON
# valida il payload
# crea il job
# restituisce <code>202 Accepted</code>

== File 3: lib/proxmox_ssh.py ==
Questo file e il cuore del provisioning.

=== Blocco 1: lettura environment ==
Righe utili: <code>11-29</code>

Funzioni:
* <code>env_required()</code>
* <code>env_int()</code>
* <code>env_bool()</code>

Servono a:
* leggere parametri obbligatori
* convertire interi
* interpretare flag booleani

=== Blocco 2: classe ProxmoxSSH ==
Righe utili: <code>32-75</code>

Questa classe:
* apre la sessione SSH
* esegue comandi
* stampa output e errori nel log del job
* scrive file remoti via SFTP

Perche e utile:
* centralizza tutte le interazioni con Proxmox

=== Blocco 3: attesa guest agent ed esecuzione comandi guest ==
Righe utili: <code>77-116</code>

Funzioni:
* <code>wait_for_guest_agent()</code>
esegue poll su <code>qm agent VMID ping</code>
* <code>guest_exec()</code>
esegue un comando dentro la VM via guest agent e aspetta l'exit status

Uso concreto nel progetto:
* attendere che cloud-init abbia davvero finito prima di fare cleanup

=== Blocco 4: helper di quoting ==
Righe utili: <code>119-124</code>

* <code>q()</code> usa <code>shlex.quote</code> per shell quoting
* <code>jq()</code> usa <code>json.dumps</code> per serializzare stringhe nel cloud-config

Questo evita errori banali di quoting e parsing.

=== Blocco 5: lettura parametri del job ==
Righe utili: <code>127-151</code>

Il file legge dall'environment:
* VMID, nome, utente, password
* CPU, RAM, disco
* rete, bridge, VLAN
* IP, gateway, CIDR
* flag avvio automatico
* storage, immagine cloud-init e default runtime

Qui il job passa da "payload web" a "parametri concreti di provisioning".

=== Blocco 6: costruzione rete ==
Righe utili: <code>153-164</code>

Se la rete e statica:
* richiede IP, gateway e CIDR
* costruisce <code>ipconfig0</code> nel formato Proxmox

Se la rete e DHCP:
* usa <code>ip=dhcp</code>

Poi costruisce <code>net0</code>:
* NIC virtio
* bridge obbligatorio
* firewall abilitato
* eventuale tag VLAN

=== Blocco 7: verifica collisione VMID ==
Righe utili: <code>166-169</code>

Prima di creare la VM, il file esegue:
<syntaxhighlight lang="bash">
qm config <VMID>
</syntaxhighlight>

Se il comando funziona, il VMID esiste gia e il job viene fermato.

=== Blocco 8: generazione snippet cloud-init ==
Righe utili: <code>171-191</code>

Questo e uno dei punti piu importanti:
* crea un file <code>pyinfra-user-<VMID>.yaml</code>
* lo salva in <code>/var/lib/vz/snippets/</code>
* definisce l'utente richiesto
* assegna gruppi <code>adm</code> e <code>sudo</code>
* imposta shell bash
* abilita sudo senza password
* inserisce la password iniziale
* abilita password auth SSH
* disabilita root

Perche esiste:
* il deploy deve creare un utente iniziale specificato dall'operatore

=== Blocco 9: lista comandi qm ==
Righe utili: <code>193-224</code>

Questo array contiene i passi di creazione macchina:
* <code>qm create</code> con nome, BIOS, machine type, RAM, CPU, NIC e seriale
* <code>qm set --efidisk0</code>
* <code>qm set --scsihw</code>
* <code>qm set --scsi0 import-from=IMAGE</code>
* <code>qm set --ide2 CLOUDINIT</code>
* <code>qm set --boot order=scsi0</code>
* <code>qm set --ciuser</code>
* <code>qm set --ipconfig0</code>
* <code>qm resize</code>

Idea pratica:
* la VM nasce come cloud image Proxmox correttamente preparata

=== Blocco 10: password cloud-init, cicustom e avvio ==
Righe utili: <code>226-238</code>

Passi:
* se c'e una password, esegue <code>qm set --cipassword</code>
* applica lo snippet custom con <code>qm set --cicustom user=...</code>
* se esiste un default <code>PROXMOX_CICUSTOM_USER</code>, lo ignora e lo segnala a log
* se richiesto, avvia la VM con <code>qm start</code>

=== Blocco 11: attesa primo boot e cleanup ==
Righe utili: <code>240-251</code>

Se la VM parte subito:
* aspetta il guest agent
* esegue dentro la VM <code>cloud-init status --wait</code>
* rimuove il riferimento <code>cicustom</code>
* cancella lo snippet da <code>/var/lib/vz/snippets/</code>

Se la VM non parte subito:
* scrive un warning
* lo snippet non puo essere eliminato immediatamente

Questo blocco esiste per ridurre il tempo in cui la password resta scritta nel file cloud-init sul nodo Proxmox.

=== Blocco 12: messaggio finale ==
Riga utile: <code>253</code>

Se tutto va bene, il log termina con il messaggio di creazione VM completata.

== Esempio di flusso completo ==
Caso:
* VMID 120
* nome <code>demo.gazzi.local</code>
* utente <code>gazzinet</code>
* rete DHCP
* bridge <code>vmbr1</code>

Flusso:
# l'utente compila la form
# JavaScript invia JSON a <code>/api/jobs/create-vm</code>
# <code>parse_payload()</code> valida tutti i campi
# <code>create_job()</code> apre il job
# <code>run_job()</code> lancia pyinfra
# <code>create_vm.py</code> richiama l'helper
# <code>proxmox_ssh.py</code> costruisce la VM
# se la VM parte subito, il sistema aspetta cloud-init e rimuove lo snippet

== Cosa leggere se devi fare modifiche ==
Se devi cambiare la UI:
* <code>app.py</code> blocchi HTML e JavaScript

Se devi cambiare validazioni:
* <code>app.py</code> blocchi <code>parse_payload()</code> e API network

Se devi cambiare il provisioning Proxmox:
* <code>lib/proxmox_ssh.py</code>

Se devi cambiare il modo in cui pyinfra lancia l'helper:
* <code>deploys/create_vm.py</code>

== Limiti di questa documentazione ==
Questa pagina e molto piu dettagliata del normale, ma continua a privilegiare:
* chiarezza
* leggibilita umana
* raggruppamento per blocchi logici

Non descrive ogni singola riga di CSS decorativo, perche quella parte non governa il deploy automatico VM. La logica operativa invece e coperta integralmente.

== Collegamenti ==
* [[Pyinfra]]
* [[Esempi Pyinfra]]
* [[Pyinfra/Deploy automatico VM Proxmox]]

Pyinfra/Implementazione deploy VM linea per linea - Cronologia

Maintenance script: Aggiunta documentazione tecnica dettagliata del deploy VM

Maintenance script: Aggiunta documentazione tecnica dettagliata del deploy VM

Maintenance script: Aggiunta documentazione tecnica dettagliata del deploy VM