Pyinfra: differenze tra le versioni

Da GazziNet.
Vai alla navigazione Vai alla ricerca
(Aggiornamento)
(Espansione pagina Pyinfra con struttura umana e link di approfondimento)
Riga 2: Riga 2:
= Pyinfra =
= Pyinfra =


'''Pyinfra''' in GazziNet non e solo una pagina teorica: al 2026-03-29 e stato usato per pubblicare una web UI operativa che consente di creare VM Proxmox via browser, con autenticazione LDAP e job eseguiti on demand.
'''Pyinfra''' in GazziNet va letto su due livelli:
* come strumento generale di automazione scritto in Python
* come implementazione concreta gia pubblicata su <code>bot.gazzi.net/pyinfra/</code> per creare VM Proxmox via browser


Questa pagina raccoglie il runbook sintetico della soluzione realmente messa in esercizio, con focus su deploy, configurazione, uso e verifiche. I dettagli sensibili restano fuori dalla wiki e vanno tenuti nei file runtime dedicati.
Questa pagina principale e pensata per una persona umana che vuole capire rapidamente:
* che cosa fa pyinfra
* quando usarlo
* dove trovare esempi semplici e avanzati
* dove trovare il runbook reale della web UI pubblicata
* dove trovare la spiegazione tecnica dell'implementazione del deploy automatico VM


== Cosa e stato realizzato ==
I dettagli sensibili non vanno messi in wiki. Password, token, cookie, backend privati e dump runtime restano fuori dalla documentazione pubblica o semi-pubblica.
* UI pubblica su <code>https://bot.gazzi.net/pyinfra/</code>
* autenticazione LDAP prima dell'accesso alla form
* runner <code>pyinfra</code> locale su <code>bot.gazzi.local</code>
* provisioning VM su Proxmox via SSH e comandi <code>qm</code>
* scelta di CPU, RAM, disco, bridge, VLAN, DHCP o IP statico
* scelta di utente e password iniziali della VM
* pulsante per trovare il primo VMID libero a partire da <code>100</code>
* lookup bridge e VLAN direttamente dal nodo Proxmox
* validazione preventiva della coppia <code>bridge + vlan</code>
* cleanup dello snippet cloud-init dopo il primo boot se la VM parte subito


== Architettura logica ==
== In una frase ==
Flusso sintetico:
Pyinfra e un motore di automazione che usa Python per descrivere inventory, logica e operazioni di deploy in modo piu programmabile rispetto ai playbook puramente YAML.
# utente apre <code>bot.gazzi.net/pyinfra/</code>
# Nginx su <code>proxy01</code> inoltra verso il servizio su <code>bot.gazzi.local</code>
# l'app Flask autentica l'utente via LDAP
# la UI crea un job locale <code>pyinfra</code>
# il job usa SSH verso Proxmox ed esegue <code>qm create</code> / <code>qm set</code>
# se richiesto, la VM parte subito e viene atteso il completamento di <code>cloud-init</code>


== Parametri gestiti dalla UI ==
== Quando ha senso usarlo ==
* VMID
Pyinfra e adatto quando:
* nome VM
* vuoi tenere deploy e configurazioni in Git
* utente amministrativo iniziale
* preferisci Python per logica, condizioni e riuso
* password iniziale
* devi automatizzare server Linux, homelab o ambienti interni
* CPU
* vuoi una separazione chiara tra form di input, validazione e runner di provisioning
* RAM
* disco
* rete: DHCP o IP statico
* bridge Proxmox
* VLAN Proxmox
* gateway
* CIDR
* avvio automatico della VM a fine creazione


Nota pratica:
Pyinfra e meno adatto quando:
* se e selezionato '''DHCP''', i campi IP statici vengono disabilitati
* il team vuole solo file dichiarativi molto semplici
* se si usa rete '''statica''', IP, gateway e CIDR diventano obbligatori
* nessuno vuole mantenere codice Python
* l'automazione deve essere totalmente guidata da un pannello visuale gia pronto


== File principali ==
== Concetti base ==
Sorgenti versionati:
Tre idee utili da capire subito:
* <code>scripts-repo/pyinfra-proxmox-webui/app.py</code>
* <code>scripts-repo/pyinfra-proxmox-webui/lib/proxmox_ssh.py</code>
* <code>scripts-repo/pyinfra-proxmox-webui/deploys/create_vm.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:
=== 1. Inventory ===
* working directory: <code>/opt/pyinfra-webui</code>
L'inventory descrive i target: host, gruppi e dati associati.
* environment file: <code>/etc/pyinfra-webui/pyinfra-webui.env</code>
* service systemd: <code>/etc/systemd/system/pyinfra-webui.service</code>
* state dir: <code>/var/lib/pyinfra-webui</code>


== Esempio environment file ==
=== 2. Operations ===
Non inserire password o token nella wiki. Usare placeholder e valorizzare i segreti solo nel file runtime.
Le operations descrivono cosa deve essere applicato ai target, oppure uno stato che vuoi rendere vero.


<syntaxhighlight lang="ini">
=== 3. Esecuzione ===
APP_HOST=0.0.0.0
Pyinfra legge inventory e dati, prepara l'ordine delle operazioni, si connette ai target ed esegue le modifiche.
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
== Nel caso GazziNet ==
PROXMOX_SSH_PORT=22
Su GazziNet pyinfra non e stato usato come esercizio teorico. E stato integrato in una soluzione completa:
PROXMOX_SSH_USER=root
* UI pubblica: <code>https://bot.gazzi.net/pyinfra/</code>
PROXMOX_SSH_PASS=CHANGEME
* autenticazione: LDAP
* runner: <code>pyinfra</code> locale su <code>bot.gazzi.local</code>
* target: Proxmox
* risultato: creazione controllata di VM con parametri espliciti


PROXMOX_IMAGE=/var/lib/vz/template/iso/noble-server-cloudimg-amd64.img
== Percorso consigliato di lettura ==
PROXMOX_STORAGE=local
Se parti da zero:
PROXMOX_CLOUDINIT_STORAGE=local
# [[Esempi Pyinfra]]
PROXMOX_BRIDGE=vmbr1
# [[Pyinfra/Deploy automatico VM Proxmox]]
PROXMOX_GATEWAY=172.16.1.1
# [[Pyinfra/Implementazione deploy VM linea per linea]]
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
Se vuoi solo usare la piattaforma pubblicata:
LDAP_USER_DN_TEMPLATE=uid={username},ou=People,dc=gazzi,dc=local
# [[Pyinfra/Deploy automatico VM Proxmox]]
</syntaxhighlight>


== Service systemd ==
Se vuoi capire il codice:
<syntaxhighlight lang="ini">
# [[Pyinfra/Implementazione deploy VM linea per linea]]
[Unit]
Description=Pyinfra Proxmox Web UI
After=network-online.target
Wants=network-online.target


[Service]
== Mappa delle pagine ==
Type=simple
* [[Esempi Pyinfra]]
User=pyinfraweb
  Guida pratica con esempi base e avanzati di pyinfra.
Group=pyinfraweb
* [[Pyinfra/Deploy automatico VM Proxmox]]
WorkingDirectory=/opt/pyinfra-webui
  Runbook umano della web UI pubblicata su bot.gazzi.net.
EnvironmentFile=/etc/pyinfra-webui/pyinfra-webui.env
* [[Pyinfra/Implementazione deploy VM linea per linea]]
ExecStart=/opt/pyinfra-webui/venv/bin/python /opt/pyinfra-webui/app.py
  Spiegazione tecnica del codice che realizza il deploy automatico di VM.
Restart=on-failure
* [[Confronto Ansible vs Pyinfra]]
RestartSec=3
  Confronto generale di approccio.
* [[Installazione Pyinfra su Fedora]]
  Installazione CLI in ambiente Fedora.


[Install]
== Esempio minimo per capire la sintassi ==
WantedBy=multi-user.target
Inventory:
<syntaxhighlight lang="python">
web_servers = [
    "web-01.example.net",
    "web-02.example.net",
]
</syntaxhighlight>
</syntaxhighlight>


== Reverse proxy ==
Deploy:
Snippet Nginx di riferimento:
<syntaxhighlight lang="python">
 
from pyinfra.operations import server
<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>
 
== Deploy o aggiornamento ==
Sequenza minima lato host applicativo:
 
<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
server.shell(
sudo systemctl daemon-reload
    name="Show uptime",
sudo systemctl enable --now pyinfra-webui.service
    commands=["uptime"],
)
</syntaxhighlight>
</syntaxhighlight>


Poi:
Esecuzione:
* copiare o aggiornare i file dell'app dentro <code>/opt/pyinfra-webui</code>
* aggiornare <code>/etc/pyinfra-webui/pyinfra-webui.env</code>
* riavviare il servizio
 
Comandi utili:
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
sudo systemctl restart pyinfra-webui.service
pyinfra inventory.py deploy.py
sudo systemctl status pyinfra-webui.service
journalctl -u pyinfra-webui.service -n 100 --no-pager
curl -sS http://127.0.0.1:18180/api/health
</syntaxhighlight>
</syntaxhighlight>


== Comportamento del provisioning ==
== Idea chiave ==
La UI raccoglie i parametri e avvia un job che:
Nel deployment VM di GazziNet, la UI non crea direttamente la VM. La UI:
* verifica che il VMID non esista gia
* raccoglie i parametri
* crea la VM cloud-init con <code>qm create</code> e <code>qm set</code>
* valida input e rete
* configura <code>net0</code> con bridge ed eventuale tag VLAN
* crea un job locale
* imposta <code>ipconfig0</code> in DHCP o statico
* genera uno snippet cloud-init per creare l'utente richiesto con sudo
* opzionalmente avvia la VM
* se la VM viene avviata subito, aspetta guest agent e <code>cloud-init status --wait</code>
* rimuove lo snippet cloud-init dopo il primo boot


== Sicurezza ==
Poi il job chiama pyinfra, e pyinfra richiama un helper Python che parla con Proxmox via SSH.
Regole da mantenere:
* non scrivere in wiki password, token, cookie o dump di sessione
* non copiare in Git segreti o backend interni inutili
* tenere i segreti in <code>/etc/pyinfra-webui/pyinfra-webui.env</code>
* usare HTTPS sul reverse proxy pubblico
* mantenere il controllo umano: il job parte solo a richiesta dell'utente autenticato


Nota importante:
Questa separazione aiuta a mantenere il flusso leggibile:
* se <code>start_after_create=false</code>, lo snippet cloud-init non puo essere rimosso subito e va pulito dopo il primo avvio completato
* frontend e login
* validazione e stato job
* runner pyinfra
* helper Proxmox


== API utili ==
== Regole documentali per questa area ==
Endpoint interni esposti dall'app:
La wiki deve contenere:
* <code>/api/health</code>
* spiegazioni umane
* <code>/api/jobs</code>
* runbook
* <code>/api/jobs/create-vm</code>
* esempi
* <code>/api/network/bridges</code>
* struttura dei file
* <code>/api/network/vlans</code>
* procedure di verifica
* <code>/api/network/validate</code>
* <code>/api/proxmox/free-vmid</code>
 
== Verifiche rapide ==
Verifiche applicative:
<syntaxhighlight lang="bash">
curl -I https://bot.gazzi.net/pyinfra/
curl -sS http://127.0.0.1:18180/api/health
</syntaxhighlight>


Verifiche systemd:
La wiki non deve contenere:
<syntaxhighlight lang="bash">
* password
systemctl status pyinfra-webui.service
* token
journalctl -u pyinfra-webui.service -n 50 --no-pager
* cookie di sessione
</syntaxhighlight>
* segreti runtime
* dump completi di backend interni


Verifiche Proxmox lato UI:
== Riferimenti esterni ==
* test lookup bridge
* [https://pyinfra.com/ Sito ufficiale]
* test lookup VLAN
* [https://docs.pyinfra.com/en/3.x/ Documentazione ufficiale]
* test validazione <code>bridge + vlan</code>
* [https://www.gazzi.net/pyinfra-proxmox-webui/ Scheda pubblica WordPress]
* test ricerca VMID libero
 
== Problemi noti ==
* il <code>guid</code> di WordPress o altri metadati editoriali non hanno relazione con questa automazione
* il cleanup automatico dello snippet cloud-init dipende dal primo boot e dalla disponibilita del guest agent
* la VLAN viene validata in base a cio che il nodo Proxmox espone al momento del controllo
 
== Riferimenti collegati ==
* [[Tips Automation]]
* [[Esempi Pyinfra]]
* [[Confronto Ansible vs Pyinfra]]
* [[Installazione Pyinfra su Fedora]]
* [https://www.gazzi.net/pyinfra-proxmox-webui/ Scheda pubblica su WordPress]
* [https://www.gazzi.net/2026/03/29/pyinfra-proxmox-webui-proxmox-ldap-bot-gazzi-net/ Articolo di dettaglio]
* [https://www.gazzi.net/2026/03/29/pyinfra-proxmox-webui-proxmox-ldap-bot-gazzi-net/ Articolo di dettaglio]


== Repository ==
== Repository ==
Sorgente versionata:
Sorgente versionata in:
* <code>scripts-repo/pyinfra-proxmox-webui/</code>
* <code>scripts-repo/pyinfra-proxmox-webui/</code>


Questa pagina wiki va tenuta come documentazione operativa ad alto livello e runbook sintetico. Segreti e dettagli sensibili restano fuori dalla wiki.
Pagine wiki versionate nello stesso repository:
* <code>scripts-repo/pyinfra-proxmox-webui/wiki/</code>

Versione delle 18:51, 29 mar 2026

Pyinfra

Pyinfra in GazziNet va letto su due livelli:

  • come strumento generale di automazione scritto in Python
  • come implementazione concreta gia pubblicata su bot.gazzi.net/pyinfra/ per creare VM Proxmox via browser

Questa pagina principale e pensata per una persona umana che vuole capire rapidamente:

  • che cosa fa pyinfra
  • quando usarlo
  • dove trovare esempi semplici e avanzati
  • dove trovare il runbook reale della web UI pubblicata
  • dove trovare la spiegazione tecnica dell'implementazione del deploy automatico VM

I dettagli sensibili non vanno messi in wiki. Password, token, cookie, backend privati e dump runtime restano fuori dalla documentazione pubblica o semi-pubblica.

In una frase

Pyinfra e un motore di automazione che usa Python per descrivere inventory, logica e operazioni di deploy in modo piu programmabile rispetto ai playbook puramente YAML.

Quando ha senso usarlo

Pyinfra e adatto quando:

  • vuoi tenere deploy e configurazioni in Git
  • preferisci Python per logica, condizioni e riuso
  • devi automatizzare server Linux, homelab o ambienti interni
  • vuoi una separazione chiara tra form di input, validazione e runner di provisioning

Pyinfra e meno adatto quando:

  • il team vuole solo file dichiarativi molto semplici
  • nessuno vuole mantenere codice Python
  • l'automazione deve essere totalmente guidata da un pannello visuale gia pronto

Concetti base

Tre idee utili da capire subito:

1. Inventory

L'inventory descrive i target: host, gruppi e dati associati.

2. Operations

Le operations descrivono cosa deve essere applicato ai target, oppure uno stato che vuoi rendere vero.

3. Esecuzione

Pyinfra legge inventory e dati, prepara l'ordine delle operazioni, si connette ai target ed esegue le modifiche.

Nel caso GazziNet

Su GazziNet pyinfra non e stato usato come esercizio teorico. E stato integrato in una soluzione completa:

  • UI pubblica: https://bot.gazzi.net/pyinfra/
  • autenticazione: LDAP
  • runner: pyinfra locale su bot.gazzi.local
  • target: Proxmox
  • risultato: creazione controllata di VM con parametri espliciti

Percorso consigliato di lettura

Se parti da zero:

  1. Esempi Pyinfra
  2. Pyinfra/Deploy automatico VM Proxmox
  3. Pyinfra/Implementazione deploy VM linea per linea

Se vuoi solo usare la piattaforma pubblicata:

  1. Pyinfra/Deploy automatico VM Proxmox

Se vuoi capire il codice:

  1. Pyinfra/Implementazione deploy VM linea per linea

Mappa delle pagine

 Guida pratica con esempi base e avanzati di pyinfra.

 Runbook umano della web UI pubblicata su bot.gazzi.net.

 Spiegazione tecnica del codice che realizza il deploy automatico di VM.

 Confronto generale di approccio.

 Installazione CLI in ambiente Fedora.

Esempio minimo per capire la sintassi

Inventory: <syntaxhighlight lang="python"> web_servers = [ 

   "web-01.example.net",
   "web-02.example.net",

] </syntaxhighlight>

Deploy: <syntaxhighlight lang="python"> from pyinfra.operations import server

server.shell( 

   name="Show uptime",
   commands=["uptime"],

) </syntaxhighlight>

Esecuzione: <syntaxhighlight lang="bash"> pyinfra inventory.py deploy.py </syntaxhighlight>

Idea chiave

Nel deployment VM di GazziNet, la UI non crea direttamente la VM. La UI:

  • raccoglie i parametri
  • valida input e rete
  • crea un job locale

Poi il job chiama pyinfra, e pyinfra richiama un helper Python che parla con Proxmox via SSH.

Questa separazione aiuta a mantenere il flusso leggibile:

  • frontend e login
  • validazione e stato job
  • runner pyinfra
  • helper Proxmox

Regole documentali per questa area

La wiki deve contenere:

  • spiegazioni umane
  • runbook
  • esempi
  • struttura dei file
  • procedure di verifica

La wiki non deve contenere:

  • password
  • token
  • cookie di sessione
  • segreti runtime
  • dump completi di backend interni

Riferimenti esterni

Repository

Sorgente versionata in:

  • scripts-repo/pyinfra-proxmox-webui/

Pagine wiki versionate nello stesso repository:

  • scripts-repo/pyinfra-proxmox-webui/wiki/
Estratto da "https://wiki.gazzi.net/index.php?title=Pyinfra&oldid=629"