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.

Illustrazione per l'articolo sulla pulizia del codice Ansible

🌐 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

#MiglioramentoPerché
1Oggetti Kubernetes via kubernetes.core.k8s invece di kubectl apply tramite shellidempotente, diff veri, funziona in check mode
2Rendere --check davvero utileun dry run prima di ogni esecuzione in produzione
3ansible-lint, yamllint e uno scanner di secret come hook pre-commit e GitHub Actionintercettare errori e secret trapelati prima che finiscano nel repo
4Test di idempotenza automaticola seconda esecuzione deve riportare changed=0
5Percorsi rescue nei playbook di aggiornamentouna reazione definita quando un aggiornamento fallisce a metà
6Spezzare i file di task grandiun file da 912 righe non è amico di nessuno
7meta/argument_specs.yml per i ruoliuna variabile mancante fallisce all’inizio, non a metà
8Unire i ruoli duplicatiun solo ruolo ClamAV invece di due quasi identici
9Fissare esattamente le versioni delle collection>= fa entrare inosservata una major release che rompe tutto
10Renovate per i pin di versioneproposte 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 --install prima girava a ogni play e accumulava ogni volta una nuova revisione. kubernetes.core.helm confronta 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_file non esiste. Funzionava solo tramite un redirect legacy verso community.general – una collection che non era nemmeno in requirements.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 versione k3s --version | awk … || echo 'not installed' non poteva mai stampare “not installed”: senza pipefail conta solo l’exit code di awk.

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 se needsDbUpgrade è 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-tags prima e dopo, identici.
  • 7 – argument specs: 23 ruoli dichiarano i loro input. “Obbligatorio” viene calcolato per tipo di host: i ruoli condivisi leggono blog_hostname su un server e nextcloud_hostname sull’altro, quindi nessuno dei due può essere obbligatorio. Verificato contro le variabili reali di tutti e tre i server. I valori del vault sono no_log – verificato che non compaiono né con -vvv né 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 è diventato 3.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é freshclam girasse una volta sola – ma avevo lasciato changed_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.asc a 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 come BINLOG MONITOR, e il modulo vedeva una differenza che non c’era.
  • 46 avvisi di deprecazione per variabili fact di primo livello (ansible_kernel invece di ansible_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 restartedAt del 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 MONITOR e 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.

Post correlati

Alcuni testi e immagini di questo sito sono creati con l’aiuto dell’IA o generati dall’IA. Dettagli