Due minuti e quarantacinque: il mio primo aggiornamento di un'app Nextcloud via Ansible (e il guard rail aggiunto appena prima)

Illustrazione per l'articolo sull'aggiornamento di Nextcloud su K3s

🌐 Anche in: English · Deutsch · Français · Español · Português · Nederlands · Polski

Momento confessione: il Nextcloud di produzione del diario di battaglia della migrazione gira su K3s da una settimana, il repo ha un playbook nextcloud-update.yml da mesi, e io non l’avevo mai lanciato davvero. Le app venivano aggiornate alla vecchia maniera, cliccando nell’interfaccia di amministrazione, oppure per niente. Oggi è cambiato. L’esecuzione in sé ha richiesto 2 minuti e 45 secondi. La parte interessante era tutto quello che c’era attorno.

Stesso flusso di lavoro di sempre: io decido, il mio co-admin AI (Claude) controlla, costruisce e verifica. E la primissima cosa che ha trovato non era un bug nella logica di aggiornamento, ma un’arma carica puntata sul piede alla riga tre.

Indice

🧭 Perché un playbook di aggiornamento separato?

Prima di tutto, una domanda che ho dovuto davvero fare: se lancio il playbook principale, le mie app vengono aggiornate? Risposta: no, ed è voluto. Ci sono due motivi indipendenti, e il playbook principale deliberatamente non copre nessuno dei due.

Motivo 1: stesso tag, immagine più nuova

Un tag d’immagine come nextcloud:34.0.4-fpm è solo un nome che punta a un’immagine. Le immagini ufficiali vengono ricostruite con lo stesso nome ogni volta che qualcosa sotto viene corretto: una correzione di sicurezza di Debian, una point release di PHP, OpenSSL. La versione di Nextcloud resta 34.0.4; il contenuto no.

I miei pod girano con imagePullPolicy: IfNotPresent: se un’immagine con quel nome sta già nello store locale di containerd, K3s non chiede mai più al registry. Quindi finché il tag nell’inventario non cambia, il playbook principale applica manifest identici, K3s non vede niente da fare e la vecchia build continua a girare all’infinito. Il playbook di aggiornamento forza il confronto con crictl pull e riavvia dopo. Lo stesso per Collabora.

Motivo 2: le app non sono nell’immagine

Questo è il motivo più grosso. La directory del codice di Nextcloud, /var/www/html, è un volume HostPath sul server (/srv/nextcloud-www), e le app dell’app store vengono installate proprio lì, accanto al core. Una nuova immagine porta un nuovo core e le app incluse. Non tocca mai le app di terze parti come audioplayer, drawio o Deck. Quelle si muovono solo con occ app:update (o con un clic nell’interfaccia di amministrazione). Il playbook principale impone solo la disposizione delle app: queste accese, queste spente, installa quelle che mancano. C’è un interruttore opt-in (nextcloud_apps_update), di default false.

Tre livelli, tre leve

Cosa cambia?EsempioLeva
Versione di Nextcloud34.0.4 → 34.0.5, oppure → 35Cambia il tag nell’inventario, lancia nextcloud-k3s.yml
Immagine ricostruita, stesso tagCorrezione di sicurezza in PHP o Debiannextcloud-update.yml (pull + riavvio)
App dell’app storeaudioplayer 3 → 4nextcloud-update.yml (occ app:update --all)

Perché non mettere tutto in un’unica esecuzione? Perché il playbook principale deve essere idempotente e prevedibile: converge verso uno stato dichiarato, e lanciarlo due volte non cambia niente la seconda volta. Gli aggiornamenti sono l’opposto: vanno a prendere qualunque novità ci sia su internet e sostituiscono codice in esecuzione. Questo merita un momento suo, un controllo del backup suo e occhi suoi sui log dopo. Altrimenti ogni piccola esecuzione di configurazione aggiornerebbe in silenzio le app di passaggio, e quando dopo qualcosa si rompe, non sapresti mai se è stata la tua modifica di configurazione o la release di qualcun altro.

🔫 L’arma puntata sul piede: hosts: nextcloud

Il play punta al gruppo d’inventario nextcloud. Quel gruppo al momento contiene l’istanza di produzione, un host di test e una seconda istanza che è nel mezzo di una migrazione: il suo database viene sovrascritto a ogni sincronizzazione fino al giorno del cutover ed è fissata esattamente alla versione del vecchio server. Dimentica --limit una volta e l’aggiornamento passa su tutti e tre, riavviando pod su una macchina che dovrebbe restare perfettamente immobile.

La correzione sono quattro righe e fa sì che il playbook si rifiuti di partire senza un limite:

- name: Update | Refuse to run without --limit
  ansible.builtin.assert:
    that: ansible_limit is defined
    fail_msg: "Run with --limit <host>, e.g. --limit cvjm - this playbook restarts Nextcloud."
  run_once: true

ansible_limit è una variabile magica che esiste solo quando è stato passato --limit. Economico, esplicito, e trasforma un “ops” in un messaggio di errore. Primo task dell’esecuzione di oggi: “All assertions passed”. 🎉

✅ Pre-flight: quattro controlli, due minuti

  • Backup fresco? Il pull giornaliero dalla macchina di backup era finito alle 12:30 con dump del DB e dati. Un aggiornamento senza un punto di ripristino fresco è un azzardo, non manutenzione.
  • Cosa cambierà davvero? occ app:update --all --showonly è il dry run. Risultato: esattamente un’app, audioplayer, che salta alla 4.0.0.
  • Baseline sana? occ status: nessuna modalità manutenzione, nessun upgrade del DB in sospeso, tutti i pod in esecuzione, 190 GB liberi. Cose che vuoi sapere prima, così dopo puoi capire se hai rotto qualcosa o se era già rotto.
  • Chi è online? Cinque utenti attivi negli ultimi 15 minuti. Due riavvii di Nextcloud e uno di Collabora significano che i documenti Office aperti vengono disconnessi. Annotato, accettato, è un tranquillo martedì all’ora di pranzo.

⚙️ Anatomia dell’esecuzione

PassoTempoPerché c’è
crictl pull Nextcloud + Collabora51 sI pod usano imagePullPolicy: IfNotPresent, quindi K3s non riscarica mai un tag da solo. Qui il tag è fissato a una patch release esatta, quindi questo ha per lo più confermato che l’immagine fissata è ancora l’immagine fissata.
Riavvio di Nextcloud42 sPrende un’immagine fresca se ce n’è una. Il deployment usa la strategia Recreate: solo un pod alla volta può toccare i volumi HostPath, quindi c’è una breve interruzione invece di un passaggio di consegne graduale.
Riavvio di Collabora20 sStessa idea per il server Office.
occ upgrade2 sL’entrypoint del container lo esegue già all’avvio; questa è la rete di sicurezza.
occ app:update --all2 saudioplayer → 4.0.0. L’app store offre solo release compatibili con la major in esecuzione, quindi questo non può tirarsi dietro qualcosa che rompa Nextcloud 34.
Riavvio di Nextcloud, di nuovo43 sQuello interessante, vedi sotto.

🧠 Perché riavviare due volte? OPcache e un’impostazione che non perdona

La configurazione di PHP gira con opcache.validate_timestamps=0. È un’impostazione di prestazioni: PHP compila ogni file una volta e non ricontrolla mai il file su disco per tutta la vita del processo. Ottimo per la velocità, ma ha una brutta conseguenza per gli aggiornamenti.

Il primo riavvio avviene prima che occ scriva qualcosa; esiste per prendere le immagini. Poi app:update sovrascrive i file PHP dell’app sul volume persistente, ma il PHP-FPM in esecuzione continua a servire il vecchio bytecode dalla sua cache. L’aggiornamento sembra fatto, app:list mostra il nuovo numero di versione, e il vecchio codice continua a girare fino al prossimo riavvio casuale. Per una correzione di sicurezza, è il peggior tipo di “fatto”. Da qui il secondo riavvio, e solo quando qualcosa è davvero cambiato.

Dettaglio divertente: questo morde solo le app aggiornate. Un’app appena installata non è mai stata in cache, quindi viene compilata da zero. Sono proprio gli aggiornamenti a non avere effetto in silenzio.

🐛 Bug n. 2: un task che diceva sempre “changed”

Il task occ upgrade riportava changed anche se non c’era niente da aggiornare. Il suo changed_when cercava l’assenza della frase “already at the latest version”, e Nextcloud 34 quella frase non la stampa più. In un’esecuzione senza effetti ora stampa solo una nota che rimanda alla documentazione sugli upgrade. L’assenza di una stringa che non esiste più è sempre vera, quindi il task dichiarava sempre una modifica.

# before: true forever on NC 34
changed_when: "'already at the latest version' not in occ_upgrade.stdout"
# after: only a real upgrade prints this
changed_when: "'Update successful' in occ_upgrade.stdout"

Innocuo oggi, visto che l’aggiornamento dell’app ha comunque fatto scattare il secondo riavvio. Ma un playbook che mente sulle modifiche ti abitua a ignorare il suo output, e un giorno quell’output conta. Lezione: cerca il segnale positivo, non l’assenza di uno vecchio.

🔍 Post-flight: fidarsi, ma verificare

  • audioplayer 4.0.0 attivo; la lista delle app disattivate invariata, quindi niente è stato acceso o spento alle mie spalle.
  • nextcloud.log dall’esecuzione: zero warning, zero errori. Nessun errore PHP nel container.
  • Collabora: la discovery risponde, il lato Nextcloud della connessione è intatto.
  • Self-test di notify_push: tutti e tre i controlli verdi. Il server push si è ricollegato da solo dopo i riavvii.
  • 5xx all’ingress: cinque richieste, tutte da telefoni e client di sincronizzazione nei secondi in cui il pod si riavviava. Previsto con Recreate; i client riprovano automaticamente.

🎯 Il succo

L’aggiornamento in sé è stata la parte meno emozionante: un’app, meno di tre minuti, log puliti. Il valore stava ai margini. Un guard rail che rende impossibile il default pericoloso, un riavvio che esiste per colpa di una sola impostazione della cache, e un controllo di stato che mentiva in silenzio dall’ultima versione major. L’infrastructure as code non rende magici gli aggiornamenti. Li rende noiosi, e noioso è esattamente ciò che vuoi dalla cosa che tocca la produzione. 🧰


📚 Altro in questa serie: Nextcloud da bare metal a K3s

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