Il tour di Ansible, parte 1: un repository, tre server – come è organizzato il codice e cosa succede durante un run
Parte 1 di un tour nel mio codice Ansible: come un repository e 34 ruoli gestiscono un blog e due Nextcloud, e cosa succede durante un run del playbook.

🌐 Anche in: English · Deutsch · Français · Español · Português · Nederlands · Polski
Prima parte di una serie sul codice Ansible dietro questo blog e due server Nextcloud. Il codice è pubblico: github.com/aptupgrademe/www_k3s; la serie descrive la release v3.3.0. La parte 1 spiega la struttura e cosa succede durante un run, le parti dalla 2 alla 6 i ruoli, i deep dive la tecnologia che c’è sotto.
Tre server, 34 ruoli, quattro playbook, circa 22.000 righe di YAML e template. Aprendo il repository per la prima volta, vedi soprattutto file. Questa parte spiega tre cose che vale la pena sapere per prime: come un unico insieme di ruoli serve due applicazioni molto diverse, da dove viene ogni valore, e cosa succede davvero tra ansible-playbook e il riepilogo finale.
Indice
🧩 Un repository per due applicazioni
Il blog (WordPress) e i due server Nextcloud a prima vista hanno poco in comune. Sotto, però, hanno bisogno delle stesse cose: un AlmaLinux hardenizzato, un firewall, SSH solo con chiave, K3s, certificati TLS, monitoraggio, log, protezione dagli attacchi brute force. Per questo i ruoli prendono il nome da dove vengono usati:
common_*gira su ogni server: firewall, SSH, K3s, Grafana, fail2ban e una buona ventina d’altri.blog_*esiste solo per WordPress,next_*solo per Nextcloud.
Due terzi del codice sono condivisi. Una correzione al firewall raggiunge tutti e tre i server con il run successivo, e una falla rivelata da un Nextcloud viene chiusa anche per il blog.
Il prezzo è una regola che non si prende mai una pausa: ogni modifica a un ruolo condiviso deve funzionare su entrambi gli stack. Come appare quando è vero solo sulla carta l’ha mostrato un bug trovato il 26 ottobre 2026: il filtro fail2ban per i login di Nextcloud controllava solo POST /login. Nextcloud però invia il suo form di login a /index.php/login. Il filtro girava su entrambi i server Nextcloud da luglio e non aveva mai contato un solo tentativo; nemmeno il rate limit davanti vedeva le richieste. È venuto fuori solo quando un test ha dato in pasto ai filtri una vera riga di log invece di controllare soltanto che fail2ban fosse in esecuzione.
Il succo: il codice condiviso fa risparmiare lavoro, ma ha bisogno di test che controllino il risultato. Un servizio configurato e in esecuzione non dimostra che faccia quello che deve.
📒 Da dove viene ogni valore
I ruoli descrivono cosa fare. L’inventory decide con cosa: quali server esistono, quali valori valgono per tutti e quali solo per uno.
hosts.ymlcontiene solo l’assegnazione: quale server appartiene al gruppoblog, quale anextcloud.group_vars/all/contiene quello che è uguale ovunque. Il file più importante lì èversions.yml: ogni versione che un playbook installa (K3s, Helm, immagini container, exporter) è esattamente in quel file, fino al livello di patch. Mailatest, mai un tag come10.11. Un tag del genere ad agosto aveva lasciato il blog su un’immagine MariaDB obsoleta, ancora in cache sul nodo, anche se Docker Hub ne aveva da tempo una più recente con lo stesso nome.host_vars/<host>/contiene due file per server:vars.ymlcon indirizzi, dimensioni e interruttori,vault.ymlcon le password, cifrato con Ansible Vault. Nessuno dei due è nel repository pubblico. Pubblico è un file.exampleaccanto a loro, che mostra quali chiavi servono a un host.
Quando un valore è definito in più punti, decide la precedenza di Ansible: i default dei ruoli sono il punto di partenza, group_vars li sovrascrive, host_vars sovrascrive entrambi. Un esempio è il filtro SSH per paese: nel ruolo è spento, e un server lo accende con una sola riga nel suo vars.yml.
Perché un valore mancante non emerga a metà di un run come un oscuro errore di template, 23 ruoli dichiarano i loro input in meta/argument_specs.yml. Ansible li controlla prima che il ruolo esegua il suo primo task.
Il succo: una versione non fissata esattamente in realtà è fissata dalla cache.
🔀 Come un ruolo condiviso distingue gli stack
Un ruolo common_* a volte deve sapere dove sta girando. Nextcloud ha MariaDB e Redis sull’host, il blog entrambi in container; il firewall quindi su Nextcloud ha bisogno di due regole in più. Ci sono tre schemi per questo, in ordine di preferenza:
- Lo dice il playbook. Ogni playbook completo imposta una variabile
stack: wordpressostack: nextcloud. È l’unico punto in cui si prende la decisione; i ruoli leggono solo questa variabile. - Un profilo per stack. I ruoli che fanno lo stesso tipo di lavoro su entrambi gli stack con percorsi diversi – per esempio le etichette SELinux per le directory montate – tengono entrambe le liste nei loro default e ne scelgono una in base a
stack. - Chiedi al server. Se un server riceve il suo indirizzo via DHCP non sta in nessuna variabile; il firewall lo chiede a NetworkManager. Senza le regole DHCP l’indirizzo sparirebbe al successivo rinnovo del lease.
Fino alla versione 3.2 i ruoli decidevano in base ai nomi dei gruppi nell’inventory. Questo si è rotto sul server di test, che sta in entrambi i gruppi: durante un’installazione del blog il firewall apriva le porte del database di Nextcloud, e Prometheus cercava di fare scraping di exporter di Nextcloud che lì non esistevano.
Il succo: la decisione va presa in un solo posto – dove si sa cosa viene installato, nel playbook, non nell’inventory.
📜 L’ordine nel playbook è una catena di dipendenze
Ci sono quattro playbook: per ogni applicazione uno per il run completo e uno per gli aggiornamenti. Un playbook completo è una lista di circa 25 ruoli, e l’ordine segue le dipendenze, non l’alfabeto:
- SELinux prima del deployment. I pod montano directory dall’host. Se queste non hanno ancora l’etichetta
container_file_t, SELinux blocca ogni scrittura, e MariaDB non parte. - Monitoraggio dopo il deployment. Prometheus fa scraping degli exporter nei pod, e fail2ban legge i log dell’ingress; entrambi esistono solo dopo il deployment.
- AIDE sempre per ultimo. AIDE ogni notte confronta i file di sistema con una baseline. Un run modifica di proposito file monitorati, quindi l’ultimo ruolo rinnova la baseline.
Ogni ruolo ha un tag con il proprio nome. Questo trasforma il playbook completo in uno strumento di precisione: --tags blog_k3s_deploy aggiorna solo gli oggetti Kubernetes. Proprio lì c’era una trappola diventata una regola fissa: un run con --tags salta l’ultimo ruolo, la baseline di AIDE resta vecchia, e di notte arriva una mail sui file modificati. Da allora ogni run con tag è seguito da un secondo run con --tags common_rkhunter,common_aide_refresh.
I playbook di aggiornamento riavviano l’applicazione e per questo sono scritti in modo difensivo: si rifiutano di girare senza --limit, non aggiornano un’istanza già bloccata in modalità manutenzione, e fanno il lavoro in un block con un rescue che mostra, se qualcosa va storto, in quale stato resta l’istanza.
Il succo: spostare un ruolo sposta una dipendenza. L’ordine fa parte del codice.
⚙️ Cosa succede durante un run
Connessione. Ansible si collega come root via SSH con una chiave; SSH non accetta password. Poi raccoglie solo i pochi fact che servono ai ruoli: distribuzione, kernel, hostname.
Prima un report. Il primo ruolo non cambia niente. Per K3s, Helm, l’ingress e cert-manager confronta cosa è installato, cosa fissa versions.yml e qual è l’ultima release. Chi avvia il run vede se qualcosa è obsoleto prima che cambi qualcosa.
Task dopo task. Ansible esegue il task 1 su ogni host del run, poi il task 2, e così via. Ogni task riporta ok (niente da fare), changed o failed. Qui sta la proprietà più importante dei ruoli: l’idempotenza. Un secondo run subito dopo il primo deve riportare changed=0. Questo trasforma il playbook in uno strumento di verifica: se riporta una modifica su un server che dovrebbe corrispondere al codice, è o drift – qualcuno ha cambiato qualcosa a mano – o un bug nel task. Per questo i task leggono prima lo stato e cambiano solo ciò che si discosta. I servizi non vengono riavviati a ogni occasione ma tramite handler che girano una volta alla fine, e solo se la loro configurazione è cambiata davvero.
Il dry run. Con --check --diff Ansible percorre ogni task, non cambia niente e mostra cosa cambierebbe. Lo script scripts/check-drift.sh filtra solo i task che cambierebbero qualcosa. Exit code 0 significa: il server è esattamente ciò che descrive il codice.
Il verdetto. Un run che finisce con ok dice solo che ogni task ha fatto quello che gli è stato detto. Se dopo l’applicazione funziona lo controllano alla fine i ruoli di verifica: da 30 a 38 check per server, un report colorato, una mail, e il run fallisce se un check critico non passa. Dal 26 ottobre 2026 tra questi ci sono test di efficacia: ogni filtro fail2ban riceve una vera riga di log, e ogni jail banna brevemente un indirizzo di test che deve arrivare nel kernel.
E sempre un host dopo l’altro: a ottobre due run paralleli sullo stesso server si sono scontrati sul lock del database dei pacchetti.
Il succo: changed=0 al secondo run non è un dettaglio estetico. È ciò che fa risaltare ogni vera deviazione.
🧪 Come una modifica arriva a un server
I server sono produzione: file di altre persone e un blog con dei lettori. Una modifica quindi passa sempre per le stesse fasi, dal veloce e locale al lento e reale:
- Modifica: il ruolo, il template o
versions.yml. - Linting:
ansible-linteyamllintsull’intero repository; al commit, gitleaks controlla anche password e chiavi. - Test senza server, dove un test esiste (ruoli Kubernetes, playbook di aggiornamento).
- Dry run con
check-drift.she la domanda: è esattamente quello che volevo? Qualsiasi altra cosa nella lista è una sorpresa da capire prima. - Run reale su un server, limitato con
--tagsa ciò che la modifica tocca. - Di nuovo il drift check: ora deve dire “no drift”.
- Commit e push; la CI controlla ancora una volta l’intero repository.
Nessuna di queste fasi si affida al fatto che qualcuno si ricordi qualcosa. L’unica regola che resta manuale: i run reali li avvia una persona, un host dopo l’altro, dopo aver letto il dry run.
🎯 Le cinque lezioni della parte 1
- I ruoli condivisi fanno risparmiare lavoro, ma solo con test che controllano l’effetto invece dello stato.
- Fissa ogni versione esattamente, in un solo posto.
- La decisione “blog o Nextcloud” va nel playbook.
- L’ordine dei ruoli è una catena di dipendenze.
- L’idempotenza trasforma un playbook in uno strumento di verifica.
🧭 Dove va il tour adesso
- Parte 2 – La piattaforma: come un AlmaLinux appena installato diventa un sistema di base con K3s, Helm, cert-manager e un ingress, con versioni esatte.
- Parte 3 – WordPress e Parte 4 – Nextcloud: le applicazioni, i loro pod e cosa succede durante gli aggiornamenti.
- Parte 5 – Sicurezza: firewall, SSH, fail2ban, hardening, SELinux, rilevamento.
- Parte 6 – Monitoraggio: Prometheus, Grafana, Loki, alert.
Ogni parte segue lo stesso schema: cosa fa un ruolo, perché è costruito così, e cosa è andato storto lungo la strada. L’ultimo punto di solito è il più istruttivo.
