Pyinfra

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

• Esempi Pyinfra: guida pratica con esempi base e avanzati di pyinfra.
• Pyinfra/Deploy automatico VM Proxmox: runbook umano della web UI pubblicata su bot.gazzi.net.
• Pyinfra/Implementazione deploy VM linea per linea: spiegazione tecnica del codice che realizza il deploy automatico di VM.
• Confronto Ansible vs Pyinfra: confronto generale di approccio.
• Installazione Pyinfra su Fedora: installazione CLI in ambiente Fedora.

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

• Sito ufficiale
• Documentazione ufficiale
• Scheda pubblica WordPress
• Articolo di dettaglio

Repository

Sorgente versionata in:

• scripts-repo/pyinfra-proxmox-webui/

Pagine wiki versionate nello stesso repository:

• scripts-repo/pyinfra-proxmox-webui/wiki/