Dieci punti, un branch: portare il mio codice Ansible da “funziona” a “è pulito”
Dieci miglioramenti al mio codice Ansible, testati senza toccare la produzione: kubernetes.core, un vero dry run, lint e secret scan, percorsi di rescue, Renovate.

🌐 Anche in: English · Deutsch · Français · Español · Português · Nederlands · Polski
Tutto è cominciato con una domanda un po’ vanitosa. Il mio repository Ansible fa girare questo blog e due server Nextcloud: 34 ruoli, quattro playbook, circa 9.000 righe di YAML, quasi 200 commit. La maggior parte di quelle righe non l’ho scritta io – l’ha scritta il mio co-amministratore IA (Claude), mentre io decidevo, testavo e lanciavo i playbook. Così gliel’ho chiesto: se capisco la maggior parte di questo codice, sono un utente Ansible avanzato?
La risposta è stata onesta e un po’ scomoda: avanzato nel leggerlo e gestirlo, sì. Avanzato nello scriverlo da zero, non ancora dimostrato. E poi ha elencato dieci cose che avrebbero migliorato il codice in sé. Io ho detto: falle tutte e dieci. Testale come si deve. Poi scrivici sopra. Questo è quel post.
Regole di base, come sempre: tutto succede su un branch Git separato, niente tocca un server di produzione finché non lo lancio io, e ogni affermazione viene testata. “Testata” si è rivelata la parte interessante.
Indice
📋 I dieci punti
| # | Miglioramento | Perché |
|---|---|---|
| 1 | Oggetti Kubernetes via kubernetes.core.k8s invece di kubectl apply tramite shell | idempotente, diff veri, funziona in check mode |
| 2 | Rendere --check davvero utile | un dry run prima di ogni esecuzione in produzione |
| 3 | ansible-lint, yamllint e uno scanner di secret come hook pre-commit e GitHub Action | intercettare errori e secret trapelati prima che finiscano nel repo |
| 4 | Test di idempotenza automatico | la seconda esecuzione deve riportare changed=0 |
| 5 | Percorsi rescue nei playbook di aggiornamento | una reazione definita quando un aggiornamento fallisce a metà |
| 6 | Spezzare i file di task grandi | un file da 912 righe non è amico di nessuno |
| 7 | meta/argument_specs.yml per i ruoli | una variabile mancante fallisce all’inizio, non a metà |
| 8 | Unire i ruoli duplicati | un solo ruolo ClamAV invece di due quasi identici |
| 9 | Fissare esattamente le versioni delle collection | >= fa entrare inosservata una major release che rompe tutto |
| 10 | Renovate per i pin di versione | proposte di aggiornamento come pull request invece di ricerche a mano |
A metà strada ho aggiunto un undicesimo desiderio: tutti i pin di versione in un unico posto, così vedo a colpo d’occhio cosa gira dove. Ne parlo al punto 10.
🧪 Primo problema: come testi codice Kubernetes senza toccare la produzione?
Nell’inventario c’era un server di test. Quando Claude ha provato a raggiungerlo, SSH ha rifiutato: host key verification failed. Probabilmente l’IP ormai appartiene a qualcun altro, quindi di proposito non si è collegato. E io la password del vault non la do in una chat, quindi nessun playbook poteva girare nemmeno contro i server veri.
La soluzione è stata elegante: un K3s usa e getta in podman rootless sul mio jump host. Un K3s completo è fallito subito (failed to find cpuset cgroup – ai container rootless quel controller non viene delegato). Ma per testare se i manifest vengono applicati in modo idempotente non servono affatto pod in esecuzione, solo l’API server. K3s ha un flag proprio per questo:
podman run -d --name k3s-test --privileged -p 127.0.0.1:16443:6443 \
docker.io/rancher/k3s:v1.36.5-k3s1 server --disable-agent \
--disable traefik --disable servicelb --disable metrics-server
Un piccolo script sostitutivo fa la parte di k3s kubectl: inoltra tutto al container e risponde “tutto ok” ai comandi che richiederebbero pod in esecuzione (exec, rollout status, wait). Il test poi fa quello che conta: applicare tutto con il codice vecchio da main (è lo stato in cui sono i server), poi far girare sopra il codice nuovo – dry run, esecuzione reale, di nuovo esecuzione reale, di nuovo dry run.
1️⃣ kubernetes.core invece di kubectl apply
Il vecchio schema compariva 29 volte: renderizzare un template in /tmp, kubectl apply -f, cancellare il file e indovinare “changed” cercando nell’output la parola configured. Il nuovo schema renderizza in memoria e parla direttamente con l’API:
- name: Redis | Apply Deployment + Service
kubernetes.core.k8s:
kubeconfig: "{{ k3s_kubeconfig }}"
state: present
apply: true
definition: "{{ item }}"
loop: "{{ lookup('ansible.builtin.template', 'redis-deployment.yml.j2') | ansible.builtin.from_yaml_all | select | list }}"
loop_control:
label: "{{ item.kind }}/{{ item.metadata.name }}"
Tre cose sono venute fuori solo grazie al test:
- Il primo dry run diceva “changed” per quasi tutto – senza un diff. Si scopre che il modulo non mostra alcun diff quando gli passi una lista di oggetti. Un’iterazione del loop per oggetto ha risolto, e ora il diff dice esattamente
image: redis:7.4.11-alpine → redis:7.4.12-alpine. - La migrazione una tantum riscrive solo l’annotation
last-applied-configuration(kubectl ci scrive dentro un"annotations":{}vuoto, il modulo no). Spec e template del pod restano identici, quindi nessun riavvio di pod – verificato tramite le revisioni dei ReplicaSet, tutte ancora a 1. - Helm:
helm upgrade --installprima girava a ogni play e accumulava ogni volta una nuova revisione.kubernetes.core.helmconfronta versione del chart e values e non fa niente se coincidono. Il trucco: Helm 4 è supportato solo dalla versione 6.5.0 della collection; il pacchetto della distro portava la 6.1.0.
Effetto collaterale che mi piace molto: i Secret di Kubernetes non passano più per un file in /tmp sul server.
2️⃣ Un dry run che significa qualcosa
In check mode, Ansible salta ogni task shell/command – compresi quelli innocui che si limitano a leggere qualcosa. I task successivi che valutano quei risultati poi falliscono o decidono sul nulla. 94 pure interrogazioni (controlli di versione, occ config:system:get, systemctl is-active …) ora portano check_mode: false. Tutto ciò che scrive resta saltato – e dove questo nasconderebbe una modifica in sospeso, un piccolo task in più la segnala.
3️⃣ Lint, secret scan, hook
La prima esecuzione di ansible-lint ha riportato 811 segnalazioni. Circa 600 erano regole di stile che contraddicono scelte deliberate (colonne allineate, nomi di variabili condivise senza prefisso del ruolo) – quelle sono disattivate con una motivazione scritta. Il resto è stato corretto. Due scoperte vere:
ansible.builtin.ini_filenon esiste. Funzionava solo tramite un redirect legacy versocommunity.general– una collection che non era nemmeno inrequirements.yml. Su un controller con ansible-core puro, il playbook di Nextcloud si sarebbe fermato proprio lì.- 27 pipe shell senza
pipefail. Per lo più innocue, ma nel controllo di versionek3s --version | awk … || echo 'not installed'non poteva mai stampare “not installed”: senzapipefailconta solo l’exit code diawk.
gitleaks ha scansionato tutti i 191 commit della storia: un solo risultato, un segnaposto PASTE_CONTENT_OF_id_rsa_HERE tra due marcatori di chiave in un vecchio file d’esempio. Accettato di proposito, documentato. Ora gli hook girano a ogni commit – e il primo commit che hanno bloccato è stato quello di Claude stesso, qualche ora dopo (indentazione YAML sbagliata in file generati). Esattamente quello a cui servono.
4️⃣ Idempotenza, testata
Il test con podman ora fa parte del repo (tests/k8s/run.sh). Fallisce se la seconda esecuzione cambia ancora qualcosa, se un pod verrebbe rifatto, se una release Helm prende una nuova revisione – o se un tag d’immagine cambiato di proposito non viene rilevato. Quest’ultimo conta: un test che non può mai fallire non dimostra niente.
Per i server veri c’è scripts/check-drift.sh <playbook> <host>: un dry run che stampa solo ciò che cambierebbe, con un diff leggibile. Subito dopo un’esecuzione reale deve dire NO DRIFT.
Strada facendo sono stati corretti alcuni task che riportavano “changed” a ogni esecuzione (download di firme, un utente del database, un modulo dnf). La scoperta più subdola è stata l’opposto: le nove impostazioni SMTP di Nextcloud venivano riscritte a ogni esecuzione e riportavano sempre “ok”. Una password della posta cambiata non sarebbe mai comparsa come modifica. Ora vengono prima lette, confrontate, e vengono scritti solo i valori diversi – passati via argv, così un apice in una password non può rompere il comando.
5️⃣ Quando un aggiornamento fallisce a metà
Il primo suggerimento di Claude è stato “nel rescue, uscire pulitamente dalla maintenance mode”. Ripensandoci si è corretto da solo: dopo un occ upgrade interrotto, spegnere la maintenance mode mette gli utenti su un’istanza aggiornata a metà. La logica adesso:
- Un controllo preliminare fuori dal blocco: installato, non in maintenance mode, nessun upgrade del DB in sospeso – altrimenti il playbook si rifiuta di partire. Fuori di proposito: il rescue deve occuparsi solo degli stati causati dall’esecuzione stessa.
- Il rescue raccoglie stato di occ, pod, eventi e le ultime righe di
nextcloud.log, e spegne la maintenance mode solo seneedsDbUpgradeè false. Poi si ferma, così nessun secondo server viene toccato. - Bonus: i playbook di aggiornamento prima riavviavano Nextcloud e Collabora a ogni esecuzione. Un piccolo ruolo nuovo confronta il digest di ogni immagine appena scaricata con quello che stanno facendo girare i pod e riavvia solo ciò che è stato davvero ricostruito – exporter e notify_push compresi.
Testato con kubectl/crictl finti in 14 scenari. E poi la parte importante: rompere di proposito il rescue (spegnere sempre la maintenance) e rilanciare il test. È diventato rosso esattamente nello scenario giusto. Prima, lo stesso test una volta aveva mostrato “tutto verde” per il motivo sbagliato – due scenari con lo stesso nome condividevano una directory e mescolavano i loro log. Il verde non significa granché finché non hai visto il test fallire.
6️⃣ a 9️⃣ Quelli più silenziosi
- 6 – spezzare: il ruolo WordPress (912 righe) ora è in sette file tematici, Grafana in tre, i ruoli di verifica in due ciascuno. La prova che non è cambiato niente:
--list-tasks --list-tagsprima e dopo, identici. - 7 – argument specs: 23 ruoli dichiarano i loro input. “Obbligatorio” viene calcolato per tipo di host: i ruoli condivisi leggono
blog_hostnamesu un server enextcloud_hostnamesull’altro, quindi nessuno dei due può essere obbligatorio. Verificato contro le variabili reali di tutti e tre i server. I valori del vault sonono_log– verificato che non compaiono né con-vvvné in un errore di validazione. - 8 – unire: un solo ruolo ClamAV e un solo ruolo SELinux con un profilo per stack, più 16 smoke check condivisi. Trappola evitata: Ansible identifica le voci cron per nome, quindi i nomi dovevano restare esattamente gli stessi – altrimenti il vecchio job avrebbe continuato a girare accanto al nuovo.
- 9 – pin:
>=3.0.0è diventato3.15.0. Il dry run di Renovate ha mostrato perché conta: aspettavano le major 5.x e 13.x.
🔟 Renovate, e tutte le versioni in un unico file
Tutti i pin di versione ora vivono in inventory/group_vars/all/versions.yml: i valori in forma compatta in alto, motivazioni e storia sotto. Renovate riceve dei regex manager proprio per queste righe e propone aggiornamenti come pull request – ogni settimana, mai fusi automaticamente. Un dry run locale con il container di Renovate ha trovato tutti i 21 pin tracciati e ha subito proposto nginx 1.31. Quello è il ramo mainline; io uso quello stabile (minor pari). Quindi ora ci sono dei guard rail:
- nginx resta sulle versioni minor pari.
- Le major (Nextcloud 35, MariaDB, Redis 8) e le minor di K3s/Calico solo dopo approvazione nella dependency dashboard, con una nota su cosa fare.
- Le PR di WP-CLI mi ricordano di aggiornare anche il checksum SHA-512 – Renovate non può calcolarlo, e senza di esso l’init container del blog rifiuterebbe il download.
📚 E la documentazione
Nuova nel repo: “Come funziona il codice Ansible” in tedesco, inglese e francese – variabili e loro precedenza, cosa succede durante un’esecuzione, come funzionano i moduli Kubernetes, schemi di idempotenza, gestione degli errori, i test e un percorso di apprendimento. Aggiornare le guide esistenti ha fatto emergere come bonus alcuni fatti superati: una vecchia versione d’immagine, una descrizione di Calico che diceva ancora “solo Nextcloud”, una tabella delle variabili che puntava al file sbagliato.
🚀 Il rollout
I test locali erano verdi. Allora ho dato a Claude il file con la password del vault (creato da me nel terminale, mai nella chat) e lui ha lanciato il controllo del drift contro i server veri. La primissima esecuzione contro il blog è andata in crash – lo script di Claude stesso è inciampato sul modulo dnf, che restituisce i suoi risultati come lista di stringhe invece che di oggetti. Corretto, rilanciato, e poi sono arrivate le scoperte vere. La maggior parte stava in codice che girava da mesi.
Cosa hanno mostrato solo i server veri
- Il ruolo Grafana non riusciva proprio a fare un dry run. Chiede all’API “la datasource esiste?” tramite il modulo
uri– che Ansible salta in check mode – e il task successivo poi valutava un risultato che non esisteva. Innocuo nelle esecuzioni reali, fatale per--check. - La mia correzione del punto 4 era incompleta. Avevo aggiunto
creates:perchéfreshclamgirasse una volta sola – ma avevo lasciatochanged_when: true, che sovrascrive il risultato “saltato, il file esiste”. Continuava a riportare “changed” ogni volta senza fare niente. - Un ping-pong di proprietà: il playbook impostava
publickey.asca root, qualcos’altro lo rimetteva a www-data – a ogni esecuzione, inosservato per mesi. - I binari di monitoraggio di Nextcloud venivano riscaricati dopo ogni riavvio. Gli archivi stanno in
/tmp, un riavvio la svuota e il task di download non aveva condizioni. Ora controlla prima la versione installata. - Un privilegio rinominato: all’utente dell’exporter di MariaDB veniva riassegnato il privilegio a ogni esecuzione. Il codice chiedeva
REPLICATION CLIENT, MariaDB 10.11 riporta lo stesso privilegio comeBINLOG MONITOR, e il modulo vedeva una differenza che non c’era. - 46 avvisi di deprecazione per variabili fact di primo livello (
ansible_kernelinvece diansible_facts['kernel']) – oggi vanno bene, in una futura release di Ansible si romperanno.
Una domanda richiedeva più di un log: il Deployment di Nextcloud sarebbe cambiato? Il suo task è no_log perché porta dei secret, quindi il diff è nascosto. Un riavvio significa un breve disservizio (strategia Recreate). Claude ha confrontato l’oggetto live con un dry run lato server dell’apply e ha stampato solo i nomi dei campi diversi, mai i valori: identico a parte l’annotation last-applied. Nessun riavvio.
Più veloce, già che c’eravamo
Ho chiesto se i ruoli potessero girare in parallelo per velocizzare. Risposta onesta: non su un solo host – Ansible esegue i task di un host uno dopo l’altro, e le vere race condition sarebbero i lock di dnf e AIDE/rkhunter che hanno bisogno dello stato finale. I guadagni sicuri stavano altrove: AIDE ora confronta e scrive la sua baseline in una scansione invece di due (da 30 secondi a 3 minuti per esecuzione sul blog), e gli oggetti Kubernetes di un template vanno all’API in una sola chiamata nelle esecuzioni normali – per oggetto solo con --diff, dove conta il diff leggibile. Solo Calico è sceso da circa 30 secondi a meno di 2.
Le esecuzioni reali
- Blog: MariaDB e Redis non toccati, WordPress riavviato una volta – ho controllato perché: l’unica differenza tra il vecchio e il nuovo template del pod era il timbro
restartedAtdel riavvio voluto dopo gli aggiornamenti dei plugin. Le release Helm sono rimaste alla revisione 87 (cert-manager) e 72 (ingress-nginx). Quei numeri dicono tutto: il vecchio codice aggiungeva una revisione a ogni esecuzione. Controllo del drift dopo: NO DRIFT. - sofie: nessun pod riavviato, revisioni Helm invariate, self-test di notify_push verde, NO DRIFT.
- cvjm (il Nextcloud grande): stesso quadro – nessun pod riavviato, revisioni Helm invariate, l’utente dell’exporter ora ha
BINLOG MONITORe non gli viene più riassegnato, NO DRIFT.
🎯 Morale
In numeri: 16 commit, 165 file toccati, 0 errori di lint, due nuove suite di test, tre server convertiti – ognuno terminato con NO DRIFT. Ma i numeri non sono il punto. La maggior parte delle scoperte vere è venuta da test a cui era permesso fallire: la dipendenza nascosta da una collection, la password della posta che non compariva mai come modifica, il diff mancante, il test verde per il motivo sbagliato – e, una volta coinvolti i server veri, una mezza dozzina di piccole bugie in codice che girava tranquillo da mesi.
E la mia domanda di partenza? Ora il repository ha un percorso di apprendimento. Il passo tre dice: scrivi un ruolo da solo, senza un modello. Quello tocca a me.
