Playbook per il rollback: ripristinare una release malfunzionante in 5 minuti

Perché i rollback fanno paura (e perché l'esercizio aiuta)

Una release può sembrare perfetta nei test e poi rompersi nei primi cinque minuti di traffico reale. La parte spaventosa di solito non è il bug: è l'incertezza: cosa è cambiato, cosa puoi annullare in sicurezza e se il rollback peggiorerà le cose.

Subito dopo un deploy, i guasti sono spesso semplici e dolorosamente visibili. Un nuovo pulsante può mandare in crash la pagina su mobile. Una modifica al backend può restituire una forma di dati sbagliata e far fallire il checkout. Una piccola modifica di configurazione può rompere login, email o pagamenti. Anche quando la correzione è facile, la pressione sale perché gli utenti osservano e ogni minuto sembra costoso.

Il panico inizia quando la via del rollback non è chiara. Le persone si pongono le stesse domande nello stesso momento: abbiamo uno snapshot? Quale versione era l'ultima buona? Se rollbackiamo l'app, cosa succede al database? Chi ha accesso per farlo? Quando queste risposte non sono già scritte, il team perde tempo a discutere invece di ripristinare il servizio.

Indovinare durante un incidente ha un costo reale. Si perde tempo, gli utenti perdono fiducia e le modifiche fatte di fretta possono causare un secondo outage oltre al primo. Anche gli ingegneri vengono tirati in troppe direzioni: debug, comunicazione e decisioni.

Una prova pratica cambia l'umore perché sostituisce l'incertezza con la memoria muscolare. Un buon rollback drill non è solo “riusciamo a revertare il codice?”. È una routine ripetibile: cosa snapshotti, cosa ripristini, cosa verifichi e chi è autorizzato ad agire. Dopo qualche esercitazione, il rollback smette di sembrare un fallimento e diventa uno strumento di sicurezza.

Se il tuo setup di deployment supporta già snapshot e restore (alcune piattaforme, inclusa Koder.ai, integrano questo nel flusso di rilascio), le esercitazioni diventano più semplici perché “tornare a un noto buono” è un'azione normale, non una procedura d'emergenza. In ogni caso, l'obiettivo è lo stesso: quando arriva il momento, nessuno deve improvvisare.

Cosa significa davvero “ripristinare in 5 minuti”

“Ripristinare in 5 minuti” non significa che tutto sia perfetto di nuovo. Significa poter riportare rapidamente gli utenti a una versione funzionante, anche se la nuova release è ancora difettosa.

Servizio prima, correzioni dopo. Se riesci a ripristinare il servizio velocemente, ti compri tempo tranquillo per trovare il bug reale.

I 5 minuti sono per l'azione, non per il dibattito

Il timer inizia quando concordate: “Stiamo rollbackando.” Non include una lunga discussione sul fatto che le cose possano recuperare da sole.

Decidete il trigger di rollback in anticipo. Per esempio: “Se gli errori al checkout restano sopra X% per 3 minuti dopo il deploy, rollbackiamo.” Quando il trigger scatta, seguite lo script.

Cosa conta come “ripristinato"

“Ripristinato” dovrebbe essere un piccolo insieme di segnali che vi dicono che gli utenti sono al sicuro e il sistema è stabile. Mantienilo stretto e facile da controllare:

• L'azione utente chiave funziona di nuovo (login, checkout, ricerca o la cosa principale che la tua app deve fare)
• L'error rate torna vicino al normale
• La latenza ritorna in un range accettabile
• Nessun crash loop o ondata di restart

Quando quei segnali sembrano buoni, fermate il timer dei 5 minuti. Tutto il resto può aspettare.

Per mantenere l'esercitazione onesta, indica esplicitamente cosa non farete durante il percorso dei 5 minuti: debug approfondito, cambi di codice o hotfix, e qualsiasi attività che diventi lavoro di ingegneria.

Scegli un approccio di rollback che il tuo team possa ripetere

Un rollback sembra veloce solo quando la decisione è in gran parte già presa. Scegli un approccio che funzioni per la maggior parte degli incidenti, poi esercitatelo finché non diventa banale.

La tua esercitazione dovrebbe rispondere a quattro domande:

• Facciamo rollback o hotfix?
• A cosa torniamo?
• Cosa innesca il rollback?
• Chi ha l'autorità per dire “fai”?

Rollback vs hotfix: scegli il default

Il rollback è la scelta migliore quando la nuova release danneggia attivamente gli utenti o i dati e hai già una versione nota come buona a cui tornare. L'hotfix è migliore quando l'impatto è piccolo, la modifica è isolata e sei sicuro di poter patchare in sicurezza.

Un default semplice funziona bene: se gli utenti non possono completare l'azione principale (checkout, login, signup) o l'error rate schizza, rollback prima e correggi poi. Riserva gli hotfix per problemi fastidiosi ma non pericolosi.

Scegli il target del rollback

Il tuo “target” dovrebbe essere qualcosa che il team può selezionare rapidamente, senza discussioni. La maggior parte dei team arriva a tre target comuni:

• La versione precedente (l'ultimo rilascio che ha superato i controlli)
• Uno snapshot di deployment che puoi ripristinare
• Un rollback solo di configurazione (feature flag o cambio di environment)

Se hai snapshot di deployment affidabili, rendili il default perché sono i più ripetibili sotto pressione. Mantieni il rollback di sola configurazione come percorso separato per i casi in cui il codice va bene ma è sbagliata un'impostazione.

Definisci anche cosa conta come “previous good”. Dovrebbe essere l'ultima release che ha completato i controlli di monitoraggio e non aveva incidenti attivi, non “quella che la gente ricorda”.

Definisci trigger e autorità

Non aspettare una riunione durante un incidente. Scrivi i trigger che avviano un rollback e rispettali. I trigger tipici includono un flusso principale rotto per più di pochi minuti, error rate o latenza oltre soglie concordate, rischio sui dati (scritture errate, addebiti duplicati) e qualsiasi problema di sicurezza o privacy introdotto dalla release.

Poi decidi chi può approvare il rollback. Scegli un ruolo (incident lead o on-call) più un backup. Tutti gli altri possono consigliare, ma non possono bloccare. Quando il trigger scatta e l'approvatore dice “rollback”, il team esegue sempre gli stessi passaggi.

Cosa snapshotare prima di ogni rilascio

Un rollback drill funziona solo se puoi tornare rapidamente a uno stato noto. Gli snapshot non sono solo “belli da avere”. Sono le ricevute che dimostrano cosa stava girando, cosa è cambiato e come tornare indietro.

Le cinque cose da catturare

Prima di ogni rilascio, assicurati di poter prendere questi elementi senza cercare nei log di chat:

• Il build esatto che hai spedito: hash del commit, numero di versione e artefatto di build (tag del container, bundle o pacchetto).
• Stato del database e piano di migrazione: quali migrazioni sono state applicate e se sono reversibili. Per cambi rischiosi, fai un backup o uno snapshot ripristinabile rapidamente.
• Configurazione al momento del deploy: feature flag, variabili d'ambiente, endpoint di terze parti e cosa è cambiato. I segreti dovrebbero stare in un sistema sicuro, ma ti serve comunque una registrazione versionata delle modifiche.
• Impostazioni di infrastruttura e routing: domini, certificati, regole del load balancer e qualsiasi switch di “dove va il traffico”.
• Una breve nota di rilascio: una frase su cosa è cambiato e una frase su come verificare un rollback riuscito.

La sicurezza del database è la trappola abituale. Un rollback veloce dell'app non aiuta se il database ora si aspetta il nuovo schema. Per migrazioni rischiose, pianifica un rilascio in due step (prima aggiungi i nuovi campi, poi cominciali a usare) così il rollback resta possibile.

Nomina gli snapshot in modo che li trovi in secondi

Usa una regola di naming unica ovunque e rendila ordinabile:

prod-2026-01-09-1420-v1.8.3-commitA1B2C3

Includi environment, timestamp, versione e commit. Se i tuoi strumenti supportano snapshot in una UI, usa la stessa regola di naming lì così chiunque può trovare il giusto punto di restore durante un incidente.

Ruoli: chi clicca cosa (e chi osserva)

Un rollback drill è più veloce e sereno quando tutti conoscono il proprio ruolo. L'obiettivo non è “tutti dentro”. È una persona che prende decisioni, una persona che esegue l'azione, una che conferma che ha funzionato e una che tiene informati gli altri.

Per team piccoli e medi questi ruoli funzionano bene (una persona può coprirne due se necessario, ma evita di unire Deployer e Verifier durante l'esercitazione):

• Incident lead (cronometrista e decisore): stabilisce l'obiettivo di successo e ordina il rollback.
• Deployer (mani sulla tastiera): esegue i passaggi di rollback esattamente come documentato e narra ciò che fa.
• Verifier (prova che funziona): esegue i controlli obbligatori e osserva i segnali chiave.
• Communicator (voce esterna): pubblica aggiornamenti brevi e regolari a stakeholder e support.

I permessi decidono se il piano è reale o solo un bel documento. Prima dell'esercitazione, accordatevi su chi è autorizzato a rollbackare la produzione e come funzionano le emergenze.

Una configurazione semplice:

• Dai al Deployer i diritti di rollback durante la rotazione on-call o le finestre di drill programmate.
• Lascia che l'Incident lead approvi l'azione (anche se non ha il pulsante).
• Assicura che il Verifier abbia accesso in sola lettura a dashboard e log.
• Imposta un'opzione break-glass (accesso auditato e limitato nel tempo).
• Testa gli accessi durante la preparazione del drill, non nel mezzo dei 5 minuti.

Se usi una piattaforma che supporta snapshot e rollback (inclusa Koder.ai), decidi chi può creare snapshot, chi può ripristinarli e dove quell'azione viene registrata.

Passo dopo passo: il runbook per il rollback drill

Un rollback drill funziona meglio quando sembra una prova antincendio: stessi passaggi, stesse parole, gli stessi posti su cui cliccare. L'obiettivo non è la perfezione. È che chiunque sia on-call possa ripristinare l'ultima versione nota buona rapidamente, senza discutere le opzioni.

Prima di iniziare

Scegli un trigger chiaro e dillo ad alta voce quando parte l'esercitazione. Esempi: “Checkout ritorna 500 per più di 1 minuto” o “Error rate è 5x il normale subito dopo il deploy.” Dirlo ad alta voce evita che il team scivoli nella modalità troubleshooting.

Tieni una breve checklist di preparazione accanto al runbook:

• Conferma che puoi vedere i segnali di salute live (uptime, error rate, flusso utente chiave)
• Conferma l'identificatore dell'ultima versione buona (tag, build, nome snapshot)
• Conferma dove si eseguono i rollback (CI/CD, console dell'hosting, UI della piattaforma)
• Conferma come mettere in pausa i nuovi deploy
• Conferma chi registra i timestamp

Il runbook dei 5 minuti

1. Avvia il timer. Una persona dichiara il trigger e la decisione: “Rollbackiamo ora.”

2. Congela i cambiamenti. Metti in pausa i nuovi deploy e interrompi le modifiche non essenziali che potrebbero cambiare il sistema a metà rollback.

3. Fai uno snapshot dell'ultima possibilità (solo se sicuro e veloce). Questa è protezione nel caso serva ricreare lo stato rotto dopo. Nominalo chiaramente e vai avanti.

4. Esegui l'azione di rollback esattamente come documentato. Non improvvisare. Leggi ad alta voce le conferme così il recorder può catturare cosa è successo.

5. Conferma che il rollback è completato in un posto di fiducia. Usa uno schermo e un segnale unici ogni volta (vista storica dei deploy, etichetta “versione corrente” o un indicatore di stato chiaro).

Subito dopo l'azione, cattura ciò che conta mentre è fresco:

• Ora della decisione (trigger dichiarato)
• Ora d'inizio rollback (primo click/comando)
• Ora completamento rollback (versione precedente attiva)
• Prima verifica verde (controllo chiave passa)
• Eventuali sorprese (permessi mancanti, pulsante poco chiaro, passaggio lento)

Se il rollback impiega più di 5 minuti, non giustificarlo. Trova il passaggio lento, correggi il runbook e ripeti l'esercitazione.

Cosa verificare dopo il rollback

Un rollback “ha funzionato” solo quando gli utenti percepiscono che ha funzionato. Non stai cercando di dimostrare solo che la vecchia versione è stata deployata. Stai dimostrando che il servizio è di nuovo utilizzabile e stabile.

Mantieni la verifica piccola e ripetibile. Se la lista è più lunga di cinque elementi, le persone la salteranno sotto stress.

I 3-5 controlli obbligatori

Usa controlli che puoi eseguire velocemente, con un chiaro pass/fail:

• L'utente può loggarsi (o registrarsi) e raggiungere la home senza errori
• La transazione principale funziona (checkout, prenotazione, invio modulo)
• Un endpoint API chiave ritorna 200 e la risposta sembra normale
• Admin/support può eseguire un'azione critica (refund, cancellazione, aggiornamento stato)
• Un flusso di confine che spesso si rompe (reset password, upload file, ricerca) funziona ancora

Dopo i controlli funzionali, dai un'occhiata al segnale di salute di sistema più semplice che ti fidi. Vuoi vedere l'error rate calare e la latenza smettere di impennarsi entro un paio di minuti.

Conferma anche che le parti meno visibili ripartono: i job in background dovrebbero processare e le code dovrebbero svuotarsi, non crescere. I controlli sul database devono essere veloci e banali: connessioni stabili, nessun accumulo di lock evidente e l'app riesce a scrivere.

Infine, testa il mondo esterno dove conta. Se puoi farlo in sicurezza, esegui un test di pagamento, conferma che le email non rimbalzano e assicurati che i webhook vengano accettati (o almeno non falliscano).

Decidi la formula di “tutto ok”

Pre-scrivi una frase così nessuno improvvisa:

“Rollback completato. Flussi core verificati (login + checkout). Error rate e latenza tornati alla normalità. Monitoraggio per 30 minuti. Prossimo aggiornamento alle 14:30.”

Esempio: una release rotta e un ripristino pulito in 5 minuti

Sono le 10:02 di un martedì. Esce una nuova release e nel giro di un minuto una fetta di utenti non riesce a loggarsi. Alcuni ricevono “sessione invalida”, altri vedono uno spinner che non finisce mai. Le registrazioni funzionano ancora, quindi il problema è facile da non notare all'inizio.

Il primo segnale di solito non è un outage drammatico. È un picco silenzioso: ticket al supporto, un calo dei login riusciti e qualche messaggio arrabbiato di utenti reali. L'on-call vede un alert “login success rate giù del 18% in 5 minuti” e il support segnala: “3 utenti non riescono a loggarsi dopo l'aggiornamento.”

Il ripristino in 5 minuti (come può apparire)

Perché il team ha praticato il drill, non discute a lungo. Confermano, decidono e agiscono.

• 10:03: On-call conferma che è reale e assegna un incident lead.
• 10:04: Decisione di rollback. Regola: se il login è rotto e non c'è una correzione sicura in 2 minuti, rollback.
• 10:05: Il Deployer avvia il rollback allo snapshot precedente noto buono.
• 10:06: Il traffico torna alla versione precedente. Il team ritesta login su web e mobile.
• 10:07: L'incident lead posta “Login ripristinato, monitoriamo per 10 minuti” e chiede al support di rispondere agli utenti coinvolti.

Cosa viene rollbackato: codice applicativo e config per i servizi web e API. Cosa resta così com'è: database e dati utente.

Se la release includeva una migrazione del database, la regola del drill è semplice: mai rollbackare il database nel percorso dei 5 minuti. Mantieni le migrazioni backward compatible o fermati e prendi un secondo parere prima del deploy.

Cosa comunicare (durante e dopo)

Durante il rollback, l'incident lead pubblica aggiornamenti brevi ogni paio di minuti: cosa vedono gli utenti, quale azione è in corso e quando il prossimo aggiornamento. Esempio: “Stiamo rollbackando l'ultima release per ripristinare il login. Prossimo aggiornamento tra 2 minuti.”

Dopo il rollback, chiudono il cerchio: “Il login è tornato alla normalità. Root cause review in corso. Condivideremo cosa è successo e cosa cambiamo per evitare ripetizioni.”

Errori comuni nell'esercitazione di rollback (e correzioni semplici)

Un rollback drill dovrebbe essere noioso. Se è stressante, probabilmente il drill sta mettendo in luce gap reali: accessi, snapshot mancanti o passaggi che esistono solo nella testa di qualcuno.

Gli errori che fanno perdere minuti

• Esercitate con accessi ipotetici, non con i permessi reali. Le persone scoprono a incidente iniziato di non poter deployare, cambiare config o raggiungere dashboard. Correzione: esegui il drill con gli stessi account e ruoli che useresti in incidente.

• Gli snapshot esistono, ma sono incompleti o difficili da trovare. Si snapshotta l'app ma si dimenticano cambi env, feature flag o routing. Oppure il nome dello snapshot è inutile. Correzione: rendi la creazione dello snapshot un passo del rilascio con regola di naming e verifica durante i drill che lo snapshot sia visibile e ripristinabile rapidamente.

• Le migrazioni del database rendono il rollback non sicuro. Uno schema non compatibile a ritroso trasforma un rollback veloce in un problema sui dati. Correzione: preferisci migrazioni additive. Se un cambiamento breaking è inevitabile, pianifica una fix forward e etichetta chiaramente la release: “rollback allowed: yes/no.”

• Dichiari il successo prima di verificare cosa sentono gli utenti. L'app è deployata, ma il login è ancora rotto o i job sono bloccati. Correzione: mantieni la verifica breve ma reale e limita il tempo.

• L'esercitazione è troppo complessa per essere ripetuta. Troppi strumenti, troppi controlli, troppe voci. Correzione: riduci il drill a una pagina e un owner. Se non si può fare da un singolo runbook e un unico canale di comunicazione, non succederà sotto pressione.

Un buon rollback drill è un'abitudine, non una performance eroica. Se non riesci a terminarlo con calma, togli passaggi finché non ci riesci, poi aggiungi solo ciò che riduce davvero il rischio.

Checklist rapida e prossimi passi

Un rollback drill funziona meglio quando tutti seguono la stessa checklist di una pagina. Tienila dove il team la guarda davvero.

Una versione compatta che puoi eseguire in meno di 10 minuti (inclusi setup e verifica):

• Prima del rilascio: conferma il punto di rollback (snapshot/versione), registra il comportamento “buono” atteso, assegna ruoli (deployer, verifier, comms).
• Trigger: dichiara “rollback iniziato”, avvia un timer, congela i nuovi deploy.
• Azione di rollback: ripristina l'ultima release nota buona, cattura cosa è stato cliccato e in quale ordine.
• Verifica: esegui 2-3 controlli critici (login, flusso principale, una integrazione o controllo API), conferma che l'error rate cali.
• Chiusura: dichiara “servizio stabile”, scrivi tre note (cosa ha funzionato, cosa ti ha rallentato, cosa cambiare), sblocca i deploy.

Esegui drill abbastanza spesso che i passaggi diventino normali. Mensilmente è un buon default. Se il tuo prodotto cambia quotidianamente, prova ogni due settimane, ma mantieni la verifica focalizzata sul percorso utente principale.

Dopo ogni esercitazione, aggiorna il runbook lo stesso giorno mentre è fresco. Archivialo con le note di rilascio e aggiungi una riga datata “ultimo test” così nessuno si fida di una procedura obsoleta.

Misura solo ciò che ti aiuta a migliorare:

• Tempo al rollback (dichiarazione -> ripristinato)
• Tempo di verifica (ripristinato -> stabile)
• Chiarezza dei ruoli (dove le persone hanno esitato o duplicato lavoro?)
• Informazioni mancanti (credenziali, permessi, posizione snapshot)

Se il tuo team usa Koder.ai, tratta snapshot e rollback come parte dell'abitudine: nomina gli snapshot in modo coerente, esercita i restore nella stessa interfaccia che userai on-call e includi controlli rapidi su domini custom e integrazioni chiave nei passi del verifier. Includerlo nel runbook mantiene l'esercitazione allineata a come effettivamente distribuisci.