Pyinfra: differenze tra le versioni

Da GazziNet.
Vai alla navigazione Vai alla ricerca
(Aggiornamento)
(Espansione)
 
(3 versioni intermedie di uno stesso utente non sono mostrate)
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]]: guida pratica con esempi base e avanzati di pyinfra.
User=pyinfraweb
* [[Pyinfra/Deploy automatico VM Proxmox]]: runbook umano della web UI pubblicata su bot.gazzi.net.
Group=pyinfraweb
* [[Pyinfra/Implementazione deploy VM linea per linea]]: spiegazione tecnica del codice che realizza il deploy automatico di VM.
WorkingDirectory=/opt/pyinfra-webui
* [[Confronto Ansible vs Pyinfra]]: confronto generale di approccio.
EnvironmentFile=/etc/pyinfra-webui/pyinfra-webui.env
* [[Installazione Pyinfra su Fedora]]: installazione CLI in ambiente Fedora.
ExecStart=/opt/pyinfra-webui/venv/bin/python /opt/pyinfra-webui/app.py
Restart=on-failure
RestartSec=3


[Install]
== Domanda pratica tipica ==
WantedBy=multi-user.target
Se devi controllare 10 server:
</syntaxhighlight>
* sul '''manager''' installi <code>pyinfra</code>, tieni inventory e deploy e da li lanci i job
* sui '''10 server target''' non installi <code>pyinfra</code>, ma devi avere accesso SSH e permessi adeguati


== Reverse proxy ==
La spiegazione completa con esempi e nella pagina:
Snippet Nginx di riferimento:
* [[Esempi Pyinfra]]


<syntaxhighlight lang="nginx">
== Esempio minimo per capire la sintassi ==
location = /pyinfra {
Inventory:
    return 301 /pyinfra/;
<pre>
}
web_servers = [
    "web-01.example.net",
    "web-02.example.net",
]
</pre>


location /pyinfra/ {
Deploy:
    proxy_pass http://BOT_GAZZI_LOCAL:18180/;
<pre>
    proxy_http_version 1.1;
from pyinfra.operations import server
    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 ==
server.shell(
Sequenza minima lato host applicativo:
    name="Show uptime",
    commands=["uptime"],
)
</pre>


<syntaxhighlight lang="bash">
Esecuzione:
sudo mkdir -p /opt/pyinfra-webui /etc/pyinfra-webui /var/lib/pyinfra-webui
<pre>
sudo chown -R pyinfraweb:pyinfraweb /opt/pyinfra-webui /var/lib/pyinfra-webui
pyinfra inventory.py deploy.py
</pre>


cd /opt/pyinfra-webui
== Idea chiave ==
python3 -m venv venv
Nel deployment VM di GazziNet, la UI non crea direttamente la VM. La UI:
./venv/bin/pip install -U pip
* raccoglie i parametri
./venv/bin/pip install -r requirements.txt
* valida input e rete
* crea un job locale


sudo install -m 0644 systemd/pyinfra-webui.service /etc/systemd/system/pyinfra-webui.service
Poi il job chiama pyinfra, e pyinfra richiama un helper Python che parla con Proxmox via SSH.
sudo systemctl daemon-reload
sudo systemctl enable --now pyinfra-webui.service
</syntaxhighlight>


Poi:
Questa separazione aiuta a mantenere il flusso leggibile:
* copiare o aggiornare i file dell'app dentro <code>/opt/pyinfra-webui</code>
* frontend e login
* aggiornare <code>/etc/pyinfra-webui/pyinfra-webui.env</code>
* validazione e stato job
* riavviare il servizio
* runner pyinfra
* helper Proxmox


Comandi utili:
== Regole documentali per questa area ==
<syntaxhighlight lang="bash">
La wiki deve contenere:
sudo systemctl restart pyinfra-webui.service
* spiegazioni umane
sudo systemctl status pyinfra-webui.service
* runbook
journalctl -u pyinfra-webui.service -n 100 --no-pager
* esempi
curl -sS http://127.0.0.1:18180/api/health
* struttura dei file
</syntaxhighlight>
* procedure di verifica


== Comportamento del provisioning ==
La wiki non deve contenere:
La UI raccoglie i parametri e avvia un job che:
* password
* verifica che il VMID non esista gia
* token
* crea la VM cloud-init con <code>qm create</code> e <code>qm set</code>
* cookie di sessione
* configura <code>net0</code> con bridge ed eventuale tag VLAN
* segreti runtime
* imposta <code>ipconfig0</code> in DHCP o statico
* dump completi di backend interni
* 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 ==
== Riferimenti esterni ==
Regole da mantenere:
* [https://pyinfra.com/ Sito ufficiale]
* non scrivere in wiki password, token, cookie o dump di sessione
* [https://docs.pyinfra.com/en/3.x/ Documentazione ufficiale]
* non copiare in Git segreti o backend interni inutili
* [https://www.gazzi.net/pyinfra-proxmox-webui/ Scheda pubblica WordPress]
* 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:
* se <code>start_after_create=false</code>, lo snippet cloud-init non puo essere rimosso subito e va pulito dopo il primo avvio completato
 
== API utili ==
Endpoint interni esposti dall'app:
* <code>/api/health</code>
* <code>/api/jobs</code>
* <code>/api/jobs/create-vm</code>
* <code>/api/network/bridges</code>
* <code>/api/network/vlans</code>
* <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:
<syntaxhighlight lang="bash">
systemctl status pyinfra-webui.service
journalctl -u pyinfra-webui.service -n 50 --no-pager
</syntaxhighlight>
 
Verifiche Proxmox lato UI:
* test lookup bridge
* test lookup VLAN
* test validazione <code>bridge + vlan</code>
* 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 attuale delle 19:21, 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

Domanda pratica tipica

Se devi controllare 10 server:

  • sul manager installi pyinfra, tieni inventory e deploy e da li lanci i job
  • sui 10 server target non installi pyinfra, ma devi avere accesso SSH e permessi adeguati

La spiegazione completa con esempi e nella pagina:

Esempio minimo per capire la sintassi

Inventory: 

web_servers = [
    "web-01.example.net",
    "web-02.example.net",
]

Deploy: 

from pyinfra.operations import server

server.shell(
    name="Show uptime",
    commands=["uptime"],
)

Esecuzione: 

pyinfra inventory.py deploy.py

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=639"