Maintenance script: Aggiunta runbook operativo deploy automatico VM Proxmox

2026-03-29T18:55:31Z

Aggiunta runbook operativo deploy automatico VM Proxmox

← Versione meno recente		Versione delle 18:55, 29 mar 2026
Riga 97:		Riga 97:
	Usare placeholder, non segreti reali:		Usare placeholder, non segreti reali:

	<~~syntaxhighlight lang="ini"~~>		<pre>
	APP_HOST=0.0.0.0		APP_HOST=0.0.0.0
	APP_PORT=18180		APP_PORT=18180
Riga 122:		Riga 122:
	LDAP_URI=ldap://LDAP_HOST:389		LDAP_URI=ldap://LDAP_HOST:389
	LDAP_USER_DN_TEMPLATE=uid={username},ou=People,dc=gazzi,dc=local		LDAP_USER_DN_TEMPLATE=uid={username},ou=People,dc=gazzi,dc=local
	</~~syntaxhighlight~~>		</pre>

	== Cosa significano le variabili ==		== Cosa significano le variabili ==
Riga 135:		Riga 135:
	== Reverse proxy ==		== Reverse proxy ==
	Snippet di riferimento:		Snippet di riferimento:
	<~~syntaxhighlight lang="nginx"~~>		<pre>
	location = /pyinfra {		location = /pyinfra {
	return 301 /pyinfra/;		return 301 /pyinfra/;
Riga 152:		Riga 152:
	proxy_redirect off;		proxy_redirect off;
	}		}
	</~~syntaxhighlight~~>		</pre>

	== Service ==		== Service ==
	<~~syntaxhighlight lang="ini"~~>		<pre>
	[Unit]		[Unit]
	Description=Pyinfra Proxmox Web UI		Description=Pyinfra Proxmox Web UI
Riga 173:		Riga 173:
	[Install]		[Install]
	WantedBy=multi-user.target		WantedBy=multi-user.target
	</~~syntaxhighlight~~>		</pre>

	== Deploy iniziale ==		== Deploy iniziale ==
	<~~syntaxhighlight lang="bash"~~>		<pre>
	sudo mkdir -p /opt/pyinfra-webui /etc/pyinfra-webui /var/lib/pyinfra-webui		sudo mkdir -p /opt/pyinfra-webui /etc/pyinfra-webui /var/lib/pyinfra-webui
	sudo chown -R pyinfraweb:pyinfraweb /opt/pyinfra-webui /var/lib/pyinfra-webui		sudo chown -R pyinfraweb:pyinfraweb /opt/pyinfra-webui /var/lib/pyinfra-webui
Riga 188:		Riga 188:
	sudo systemctl daemon-reload		sudo systemctl daemon-reload
	sudo systemctl enable --now pyinfra-webui.service		sudo systemctl enable --now pyinfra-webui.service
	</~~syntaxhighlight~~>		</pre>

	== Aggiornamento ==		== Aggiornamento ==
	<~~syntaxhighlight lang="bash"~~>		<pre>
	cd /opt/pyinfra-webui		cd /opt/pyinfra-webui
	./venv/bin/pip install -r requirements.txt		./venv/bin/pip install -r requirements.txt
	sudo systemctl restart pyinfra-webui.service		sudo systemctl restart pyinfra-webui.service
	</~~syntaxhighlight~~>		</pre>

	== Verifiche rapide ==		== Verifiche rapide ==
	Applicative:		Applicative:
	<~~syntaxhighlight lang="bash"~~>		<pre>
	curl -I https://bot.gazzi.net/pyinfra/		curl -I https://bot.gazzi.net/pyinfra/
	curl -sS http://127.0.0.1:18180/api/health		curl -sS http://127.0.0.1:18180/api/health
	</~~syntaxhighlight~~>		</pre>

	Service:		Service:
	<~~syntaxhighlight lang="bash"~~>		<pre>
	systemctl status pyinfra-webui.service		systemctl status pyinfra-webui.service
	journalctl -u pyinfra-webui.service -n 100 --no-pager		journalctl -u pyinfra-webui.service -n 100 --no-pager
	</~~syntaxhighlight~~>		</pre>

	Funzionali:		Funzionali:

Maintenance script: Aggiunta runbook operativo deploy automatico VM Proxmox

2026-03-29T18:51:30Z

Aggiunta runbook operativo deploy automatico VM Proxmox

Nuova pagina

__NOTOC__
= Pyinfra/Deploy automatico VM Proxmox =

Questa pagina descrive la soluzione concreta pubblicata su <code>bot.gazzi.net/pyinfra/</code>. L'obiettivo non e insegnare pyinfra in astratto, ma permettere a una persona umana di capire come e fatta l'automazione, come si usa e come si mantiene.

== Obiettivo ==
Consentire la creazione guidata di VM Proxmox via browser, con:
* autenticazione LDAP
* validazione dei parametri
* job serializzati
* log consultabili
* provisioning reale eseguito via pyinfra

== Cosa vede l'utente ==
La form pubblica consente di inserire:
* VMID
* nome VM
* utente amministrativo iniziale
* password iniziale
* CPU
* RAM
* disco
* rete DHCP o statica
* bridge
* VLAN
* gateway
* CIDR
* scelta se avviare subito la VM

Pulsanti di supporto:
* ricerca del primo VMID libero a partire da <code>100</code>
* elenco bridge disponibili
* elenco VLAN disponibili sul bridge scelto

== Flusso umano ==
Una persona normale puo leggere il sistema cosi:
# apre la pagina
# fa login LDAP
# compila i parametri
# verifica rete e VMID
# preme '''Crea VM'''
# vede partire il job
# osserva il log recenti nella stessa pagina

== Flusso tecnico ==
# Nginx pubblica <code>/pyinfra/</code>
# Flask gestisce login, pagina, API e job
# il job lancia <code>pyinfra @local</code>
# il deploy pyinfra richiama un helper Python
# l'helper apre una sessione SSH verso Proxmox
# Proxmox crea la VM e la configura con cloud-init
# se la VM parte subito, il sistema aspetta il primo boot e pulisce lo snippet cloud-init

== Componenti ==
=== 1. Frontend Flask ===
Serve HTML direttamente dall'app e contiene:
* form
* validazioni lato browser
* chiamate AJAX alle API interne
* lista job recenti

=== 2. Login LDAP ===
L'utente non entra direttamente se non ha credenziali LDAP valide.

=== 3. API interne ===
Le API servono per:
* health check
* elenco job
* lookup bridge
* lookup VLAN
* validazione bridge + VLAN
* ricerca VMID libero
* creazione job

=== 4. Runner pyinfra ===
Pyinfra viene eseguito in locale con inventario implicito <code>@local</code>.

=== 5. Helper Proxmox ===
L'helper Python usa <code>paramiko</code> e comandi <code>qm</code> per creare la VM.

== File importanti ==
Versionati:
* <code>scripts-repo/pyinfra-proxmox-webui/app.py</code>
* <code>scripts-repo/pyinfra-proxmox-webui/deploys/create_vm.py</code>
* <code>scripts-repo/pyinfra-proxmox-webui/lib/proxmox_ssh.py</code>
* <code>scripts-repo/pyinfra-proxmox-webui/systemd/pyinfra-webui.service</code>
* <code>scripts-repo/pyinfra-proxmox-webui/proxy01-bot-pyinfra-location.conf.example</code>
* <code>scripts-repo/pyinfra-proxmox-webui/.env.example</code>

Runtime:
* <code>/opt/pyinfra-webui</code>
* <code>/etc/pyinfra-webui/pyinfra-webui.env</code>
* <code>/etc/systemd/system/pyinfra-webui.service</code>
* <code>/var/lib/pyinfra-webui</code>

== Esempio ragionato di environment file ==
Usare placeholder, non segreti reali:

<syntaxhighlight lang="ini">
APP_HOST=0.0.0.0
APP_PORT=18180
APP_BASE_PATH=/pyinfra
APP_TOKEN=CHANGEME
APP_SECRET_KEY=CHANGEME
APP_STATE_DIR=/var/lib/pyinfra-webui

PROXMOX_SSH_HOST=PROXMOX_HOST
PROXMOX_SSH_PORT=22
PROXMOX_SSH_USER=root
PROXMOX_SSH_PASS=CHANGEME

PROXMOX_IMAGE=/var/lib/vz/template/iso/noble-server-cloudimg-amd64.img
PROXMOX_STORAGE=local
PROXMOX_CLOUDINIT_STORAGE=local
PROXMOX_BRIDGE=vmbr1
PROXMOX_GATEWAY=172.16.1.1
PROXMOX_CPU_TYPE=x86-64-v2-AES
PROXMOX_CIUSER=ubuntu
PROXMOX_CIPASSWORD=CHANGEME
PROXMOX_CICUSTOM_USER=local:snippets/gazzi-ubuntu-user.yaml

LDAP_URI=ldap://LDAP_HOST:389
LDAP_USER_DN_TEMPLATE=uid={username},ou=People,dc=gazzi,dc=local
</syntaxhighlight>

== Cosa significano le variabili ==
* <code>APP_HOST</code> e <code>APP_PORT</code>: bind locale del servizio Flask
* <code>APP_BASE_PATH</code>: prefisso usato quando l'app sta dietro reverse proxy su <code>/pyinfra</code>
* <code>APP_TOKEN</code>: token opzionale per protezione addizionale API
* <code>APP_SECRET_KEY</code>: chiave sessione Flask
* <code>APP_STATE_DIR</code>: directory per log e stato job
* <code>PROXMOX_*</code>: connessione e default di provisioning
* <code>LDAP_*</code>: endpoint e template DN per login utente

== Reverse proxy ==
Snippet di riferimento:
<syntaxhighlight lang="nginx">
location = /pyinfra {
return 301 /pyinfra/;
}

location /pyinfra/ {
proxy_pass http://BOT_GAZZI_LOCAL:18180/;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Port $server_port;
proxy_set_header X-Forwarded-Prefix /pyinfra;
proxy_redirect off;
}
</syntaxhighlight>

== Service ==
<syntaxhighlight lang="ini">
[Unit]
Description=Pyinfra Proxmox Web UI
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=pyinfraweb
Group=pyinfraweb
WorkingDirectory=/opt/pyinfra-webui
EnvironmentFile=/etc/pyinfra-webui/pyinfra-webui.env
ExecStart=/opt/pyinfra-webui/venv/bin/python /opt/pyinfra-webui/app.py
Restart=on-failure
RestartSec=3

[Install]
WantedBy=multi-user.target
</syntaxhighlight>

== Deploy iniziale ==
<syntaxhighlight lang="bash">
sudo mkdir -p /opt/pyinfra-webui /etc/pyinfra-webui /var/lib/pyinfra-webui
sudo chown -R pyinfraweb:pyinfraweb /opt/pyinfra-webui /var/lib/pyinfra-webui

cd /opt/pyinfra-webui
python3 -m venv venv
./venv/bin/pip install -U pip
./venv/bin/pip install -r requirements.txt

sudo install -m 0644 systemd/pyinfra-webui.service /etc/systemd/system/pyinfra-webui.service
sudo systemctl daemon-reload
sudo systemctl enable --now pyinfra-webui.service
</syntaxhighlight>

== Aggiornamento ==
<syntaxhighlight lang="bash">
cd /opt/pyinfra-webui
./venv/bin/pip install -r requirements.txt
sudo systemctl restart pyinfra-webui.service
</syntaxhighlight>

== Verifiche rapide ==
Applicative:
<syntaxhighlight lang="bash">
curl -I https://bot.gazzi.net/pyinfra/
curl -sS http://127.0.0.1:18180/api/health
</syntaxhighlight>

Service:
<syntaxhighlight lang="bash">
systemctl status pyinfra-webui.service
journalctl -u pyinfra-webui.service -n 100 --no-pager
</syntaxhighlight>

Funzionali:
* test login LDAP
* test bridge disponibili
* test VLAN disponibili
* test validazione bridge + VLAN
* test ricerca VMID libero
* test provisioning di una VM reale o di test

== Esempio di percorso reale ==
Caso semplice:
* rete in DHCP
* bridge scelto manualmente
* nessuna VLAN
* VM avviata subito

Caso avanzato:
* rete statica
* bridge scelto da lookup
* VLAN scelta da lookup
* VMID trovato automaticamente
* utente iniziale definito dall'operatore

== Sicurezza ==
Punti importanti:
* non mettere segreti in wiki o Git
* usare sempre HTTPS sul path pubblico
* il job parte solo a richiesta dell'utente autenticato
* la UI accetta un solo job alla volta per ridurre collisioni banali
* lo snippet cloud-init viene rimosso dopo il primo boot solo se la VM parte subito

== Limiti noti ==
* se <code>start_after_create=false</code>, lo snippet cloud-init resta finche la VM non completa il primo avvio
* la validazione VLAN dipende da cio che Proxmox espone in quel momento
* la pagina non sostituisce un orchestratore completo multi-tenant: e un ingresso operativo controllato

== Dove leggere il codice ==
Per la spiegazione dettagliata:
* [[Pyinfra/Implementazione deploy VM linea per linea]]

Per gli esempi generali:
* [[Esempi Pyinfra]]

Pyinfra/Deploy automatico VM Proxmox - Cronologia

Maintenance script: Aggiunta runbook operativo deploy automatico VM Proxmox

Maintenance script: Aggiunta runbook operativo deploy automatico VM Proxmox