Pyinfra: differenze tra le versioni

Da GazziNet.
Vai alla navigazione Vai alla ricerca
(Creazione pagina introduttiva su pyinfra con esempi e link ufficiali)
 
(Espansione)
 
(4 versioni intermedie di uno stesso utente non sono mostrate)
Riga 1: Riga 1:
__NOTOC__
= Pyinfra =
= Pyinfra =


'''Pyinfra''' e uno strumento open source di automazione e deploy infrastrutturale scritto in Python. Può essere usato sia per comandi ad-hoc sia per deploy ripetibili definiti in file Python versionabili in Git.
'''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


== Concetto base ==
Questa pagina principale e pensata per una persona umana che vuole capire rapidamente:
Pyinfra lavora con due elementi principali:
* che cosa fa pyinfra
* '''Inventory''': host, gruppi e dati associati agli host.
* quando usarlo
* '''Operations''': stato desiderato o comandi da applicare ai target.
* 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


L'approccio e vicino ad Ansible sul piano operativo, ma invece di descrivere i deploy soprattutto in YAML, pyinfra usa Python.
I dettagli sensibili non vanno messi in wiki. Password, token, cookie, backend privati e dump runtime restano fuori dalla documentazione pubblica o semi-pubblica.


== Come funziona ==
== In una frase ==
Secondo la documentazione ufficiale, l'esecuzione avviene in cinque fasi:
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.
# lettura di inventory e data
# connessione ai target
# preparazione con rilevamento cambiamenti e ordine operazioni
# esecuzione delle modifiche
# disconnessione e cleanup


Un punto importante e che pyinfra prepara prima l'ordine delle operazioni e poi le esegue. Questo permette di mantenere l'ordine logico delle operazioni, eseguendo ogni singola operation in parallelo sui target rilevanti.
== 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


== Inventory ==
Pyinfra e meno adatto quando:
Un inventory pyinfra contiene:
* il team vuole solo file dichiarativi molto semplici
* host
* nessuno vuole mantenere codice Python
* gruppi
* l'automazione deve essere totalmente guidata da un pannello visuale gia pronto
* dati di gruppo
* dati per singolo host


Esempio minimale:
== Concetti base ==
<pre>
Tre idee utili da capire subito:
web_servers = [
 
    "web-01.example.net",
=== 1. Inventory ===
    "web-02.example.net",
L'inventory descrive i target: host, gruppi e dati associati.
]


db_servers = [
=== 2. Operations ===
    ("db-01.example.net", {"install_postgres": True}),
Le operations descrivono cosa deve essere applicato ai target, oppure uno stato che vuoi rendere vero.
]
</pre>


I dati associati agli host o ai gruppi possono essere usati nel deploy Python tramite `host.data`.
=== 3. Esecuzione ===
Pyinfra legge inventory e dati, prepara l'ordine delle operazioni, si connette ai target ed esegue le modifiche.


== Operations ==
== Nel caso GazziNet ==
Le operations descrivono cosa deve essere vero sul sistema target. In molti casi non rappresentano un'azione imperativa ma uno '''stato desiderato'''.
Su GazziNet pyinfra non e stato usato come esercizio teorico. E stato integrato in una soluzione completa:
* UI pubblica: <code>https://bot.gazzi.net/pyinfra/</code>
* autenticazione: LDAP
* runner: <code>pyinfra</code> locale su <code>bot.gazzi.local</code>
* target: Proxmox
* risultato: creazione controllata di VM con parametri espliciti


Esempio:
== Percorso consigliato di lettura ==
<pre>
Se parti da zero:
from pyinfra.operations import apt, files
# [[Esempi Pyinfra]]
# [[Pyinfra/Deploy automatico VM Proxmox]]
# [[Pyinfra/Implementazione deploy VM linea per linea]]


apt.packages(
Se vuoi solo usare la piattaforma pubblicata:
    name="Install vim",
# [[Pyinfra/Deploy automatico VM Proxmox]]
    packages=["vim"],
    update=True,
)


files.file(
Se vuoi capire il codice:
    name="Ensure log file exists",
# [[Pyinfra/Implementazione deploy VM linea per linea]]
    path="/var/log/app.log",
    user="app",
    group="app",
    mode="644",
)
</pre>


Se il target e gia nello stato richiesto, pyinfra non applica cambiamenti ulteriori.
== 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.


== Comandi ad-hoc ==
== Domanda pratica tipica ==
Pyinfra puo essere usato anche direttamente da CLI senza creare un deploy completo.
Se devi controllare 10 server:
* 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


Esempi:
La spiegazione completa con esempi e nella pagina:
<pre>
* [[Esempi Pyinfra]]
pyinfra @local exec -- echo "hello world"
pyinfra my-server.net exec -- uptime
pyinfra @docker/ubuntu:22.04 exec -- uname -a
</pre>


== Esempio base di deploy ==
== Esempio minimo per capire la sintassi ==
Inventory:
Inventory:
<pre>
<pre>
my_hosts = [
web_servers = [
     ("ubuntu2204", {
     "web-01.example.net",
        "ssh_port": 2222,
     "web-02.example.net",
        "ssh_hostname": "localhost",
        "ssh_user": "vagrant",
        "_sudo": True,
    }),
     "my-server.net",
]
]
</pre>
</pre>
Riga 91: Riga 88:
Deploy:
Deploy:
<pre>
<pre>
from pyinfra.operations import apt
from pyinfra.operations import server


apt.packages(
server.shell(
     name="Ensure vim is installed",
     name="Show uptime",
     packages=["vim"],
     commands=["uptime"],
    update=True,
)
)
</pre>
</pre>
Riga 105: Riga 101:
</pre>
</pre>


== Differenze pratiche rispetto ad Ansible ==
== Idea chiave ==
* usa '''Python''' invece di fare affidamento principalmente su YAML
Nel deployment VM di GazziNet, la UI non crea direttamente la VM. La UI:
* e comodo per chi vuole logica, condizioni e riuso direttamente nel linguaggio
* raccoglie i parametri
* mantiene il modello inventory + operazioni + stato desiderato
* valida input e rete
* puo essere piu naturale per team che preferiscono automazione programmabile piuttosto che playbook dichiarativi
* crea un job locale


== Quando ha senso usarlo ==
Poi il job chiama pyinfra, e pyinfra richiama un helper Python che parla con Proxmox via SSH.
* homelab e server Linux
* provisioning e configurazioni ripetibili
* deploy gestiti in Git
* ambienti dove Python e gia parte del flusso operativo


== Limiti da tenere presenti ==
Questa separazione aiuta a mantenere il flusso leggibile:
* richiede maggiore familiarita con Python rispetto a strumenti piu dichiarativi
* frontend e login
* alcuni team preferiscono YAML per leggibilita immediata lato operations
* validazione e stato job
* va progettato con attenzione quando la logica dipende da fatti che possono cambiare durante il deploy
* runner pyinfra
* helper Proxmox


== Installazione ==
== Regole documentali per questa area ==
Secondo la documentazione ufficiale, il metodo consigliato e:
La wiki deve contenere:
<pre>
* spiegazioni umane
uv tool install pyinfra
* runbook
pyinfra --version
* esempi
</pre>
* struttura dei file
* procedure di verifica


Alternative supportate: `pipx` oppure `pip` in virtual environment.
La wiki non deve contenere:
* password
* token
* cookie di sessione
* segreti runtime
* dump completi di backend interni


== Link ufficiali ==
== Riferimenti esterni ==
* [https://pyinfra.com/ Sito ufficiale]
* [https://pyinfra.com/ Sito ufficiale]
* [https://docs.pyinfra.com/en/3.x/ Documentazione]
* [https://docs.pyinfra.com/en/3.x/ Documentazione ufficiale]
* [https://docs.pyinfra.com/en/3.x/getting-started.html Getting Started]
* [https://www.gazzi.net/pyinfra-proxmox-webui/ Scheda pubblica WordPress]
* [https://docs.pyinfra.com/en/3.x/inventory-data.html Inventory & Data]
* [https://www.gazzi.net/2026/03/29/pyinfra-proxmox-webui-proxmox-ldap-bot-gazzi-net/ Articolo di dettaglio]
* [https://docs.pyinfra.com/en/3.x/using-operations.html Using Operations]
 
* [https://docs.pyinfra.com/en/3.x/deploy-process.html How pyinfra Works]
== Repository ==
Sorgente versionata in:
* <code>scripts-repo/pyinfra-proxmox-webui/</code>
 
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"