Tornare indietro su Workers: versioni, gradual deployments e rollback quando un deploy si rompe

Questo pezzo è per chi deploya su Cloudflare Workers: a mano, da CI o lasciando fare a un agente. Spiega come si torna indietro quando un deploy rompe la produzione. Non racconto un incidente: è una guida costruita sulla documentazione ufficiale di Cloudflare, letta il 25 ottobre 2026, con wrangler 4.152.0 come versione di riferimento su npm.

In breve:

• Ogni modifica a codice o configurazione crea una versione. Un deployment decide quali versioni servono traffico: una al 100%, oppure due divise a percentuale.
• wrangler deploy crea una versione e la manda subito al 100%. Con wrangler versions upload e wrangler versions deploy separi i due passi e puoi rilasciare al 5%, al 10%, al 50%.
• wrangler rollback crea all'istante un nuovo deployment con una versione precedente. Puoi scegliere tra le ultime 100.
• Il rollback riporta indietro il codice. Non tocca le risorse collegate: dati di D1, KV, R2 e Durable Objects restano come sono.
• Un rollback viene rifiutato in due casi. Nel frattempo è cambiato il ciclo di vita di una classe Durable Object. Oppure la versione di destinazione punta a un bucket R2, un namespace KV o una coda che non esistono più.
• Se a rompersi sono i dati, il rimedio non è il rollback del Worker. Per D1 c'è Time Travel, con tutti i suoi limiti.

Versioni e deployment: le due parole che servono

La pagina Versions & deployments definisce i due concetti. Una versione cattura lo stato completo del Worker in un momento: codice bundlato, asset statici, binding e impostazioni di compatibilità. Ha un ID univoco e registra chi l'ha creata, quando e da dove. Puoi aggiungerle un messaggio e un tag.

Un deployment è la scelta di quali versioni servono traffico. Può contenere una versione al 100% oppure due versioni con il traffico diviso. Anche il deployment registra autore, data e versioni incluse.

C'è una nota che pesa su tutto il resto. Secondo la stessa pagina, le modifiche allo stato di KV, R2, Durable Objects e D1 non vengono tracciate dalle versioni. La versione sa a quale database sei collegato. Non sa cosa c'è dentro.

Per vedere la storia ti bastano due comandi:

npx wrangler versions list      # le versioni più recenti, con ID, autore, origine, tag e messaggio
npx wrangler deployments list   # i deployment più recenti
npx wrangler deployments status # cosa sta servendo traffico adesso

Secondo la reference dei comandi Wrangler, versions list e deployments list mostrano gli ultimi 10 elementi. La stessa storia è nella dashboard, in Workers & Pages > il tuo Worker > Deployments.

Il default: un comando, subito al 100%

La pagina Deployment management elenca tre strade che creano una versione e la mandano subito al 100% del traffico: wrangler deploy, Workers Builds e la Script Upload API.

È il percorso più comodo. È anche quello in cui un errore arriva a tutti gli utenti nello stesso momento. Se il deploy lo lancia un agente o una pipeline a ogni push, stai usando questa strada. Che tu lo sappia o no.

Un dettaglio facile da perdere riguarda i segreti. La reference Wrangler spiega che anche wrangler secret put crea una nuova versione e la deploya subito. Cambiare una chiave API è quindi a tutti gli effetti un deploy in produzione.

Separare upload e deploy

Lo stesso documento mostra come dividere i due passi. Prima carichi una versione senza mandarla in produzione:

npx wrangler versions upload --tag v42 --message "nuovo checkout"

Poi decidi quando farla diventare attiva:

npx wrangler versions deploy

Il comando è interattivo: scegli la versione e la percentuale. Ci sono alcuni vincoli dichiarati nella documentazione:

• Il primo upload di un progetto nuovo va fatto con C3 o wrangler deploy. Un versions upload come primo caricamento fallisce.
• versions upload non supporta la sintassi service worker: serve il formato ES modules.
• Le modifiche a route, domini e cron trigger non viaggiano con la versione. Si applicano con wrangler triggers deploy.
• Un upload che cambia il ciclo di vita di una classe Durable Object, cioè crea, elimina, rinomina o trasferisce una classe, non è supportato. Quel cambio passa solo da wrangler deploy.

Per i segreti c'è il comando gemello: wrangler versions secret put crea una nuova versione senza deployarla. È quello che la pagina Secrets indica se usi i gradual deployments.

Provare una versione prima di darle traffico

Prima di dare traffico a una versione puoi provarla in due modi.

Il primo sono le Version URLs, che prima si chiamavano preview URLs. versions upload restituisce un indirizzo nel formato <prefisso-versione>-<nome-worker>.<sottodominio>.workers.dev. Con --preview-alias staging ottieni un alias leggibile. Le Version URLs sono pubbliche se attive: per chiuderle serve Cloudflare Access. Non vengono generate per i Worker che implementano un Durable Object, e non ci sono log per queste richieste.

Il secondo sono le version overrides. Crei un deployment con la nuova versione allo 0% e la vecchia al 100%. Poi mandi le tue richieste di prova alla nuova con un header:

npx wrangler versions deploy <ID_NUOVA>@0% <ID_VECCHIA>@100% -y

curl -s https://example.com \
  -H 'Cloudflare-Workers-Version-Overrides: my-worker="<ID_NUOVA>"'

L'override vale solo se la versione è nel deployment corrente. La documentazione avverte che dopo una modifica possono servire un paio di secondi perché sia disponibile ovunque. Se l'header non viene applicato, la richiesta segue le percentuali normali. Il vantaggio rispetto alle Version URLs è che la prova passa dal tuo dominio, con le impostazioni di sicurezza e performance della zona.

Gradual deployments: rilasciare a percentuale

I gradual deployments dividono il traffico tra due versioni. La nuova prende una quota, il resto resta sulla vecchia. Servono Wrangler 3.40.0 o successivo, e prima della 3.73.0 il flag --x-versions.

La forma non interattiva è documentata così:

npx wrangler versions deploy <ID_NUOVA>@10% <ID_VECCHIA>@90% -y

Alzi la percentuale con lo stesso comando, fino al 100%. Puoi creare un gradual deployment solo con le ultime 100 versioni caricate. Il changelog di Cloudflare dell'11 settembre 2025 ha portato quel limite da 10 a 100.

Il punto debole si chiama version skew, ed è descritto nella stessa pagina. Ogni richiesta viene assegnata a una versione in modo indipendente. Lo stesso utente può ricevere l'HTML dalla versione nuova e un asset dalla vecchia. Con file che hanno l'hash nel nome, tipo index-a1b2c3d4.js, il risultato è un 404 e una pagina rotta.

Il rimedio è la version affinity. Imposti l'header Cloudflare-Workers-Version-Key con un identificativo stabile, come l'ID utente in un cookie. La piattaforma assegna ogni chiave sempre alla stessa versione, finché dura il deployment. Si configura con una Transform Rule sulla zona. Non funziona sui domini *.workers.dev.

Lo skew esiste anche tra Worker diversi. Se il Worker A chiama il Worker B con un service binding, i due possono trovarsi in punti diversi del rispettivo rilascio. Le version overrides servono anche qui, ma solo per le chiamate fetch(): con RPC non si possono passare header.

Gradual deployments e Durable Objects

Con i Durable Objects le regole cambiano. La pagina With Durable Objects spiega che di ogni Durable Object può girare una sola versione alla volta. Durante un rilascio graduale ogni oggetto viene assegnato a una versione, e la tiene finché non crei un nuovo deployment.

Cloudflare garantisce che, per un dato deployment, le richieste a un oggetto usano sempre la stessa versione. Un oggetto viene resettato quando cambia versione. La documentazione chiede di tenere compatibili in avanti e all'indietro le API tra il Durable Object e il Worker che lo chiama. Con i gradual deployments è ancora più probabile che versioni diverse si parlino.

I cambi di ciclo di vita delle classi sono operazioni atomiche. Una volta deployati, non puoi più fare rollback a una versione precedente. Il consiglio della documentazione è deployarli da soli, separati da altre modifiche al codice.

Il rollback: un comando, e cosa fa davvero

La pagina Rollbacks e la reference Wrangler descrivono il comando:

npx wrangler rollback   # torna alla versione caricata prima dell'ultima

npx wrangler rollback <VERSION_ID> --message "torno a v41: errori 500 sul checkout"   # versione precisa, senza prompt

Senza ID, il comando usa la versione caricata prima dell'ultima. Attenzione: caricata, non deployata. Se nel frattempo hai fatto un versions upload mai andato in produzione, il default potrebbe non essere la versione che pensi. Con --message salti i prompt di conferma, che è quello che serve in uno script.

Il rollback crea subito un nuovo deployment con la versione scelta. Diventa attivo su tutte le route e i domini. Funziona anche da un deployment diviso: le due versioni vengono sostituite da quella scelta al 100%. Puoi tornare a una qualsiasi delle ultime 100 versioni pubblicate.

Dalla dashboard: Workers & Pages > il tuo Worker > Deployments, poi il menu a tre puntini sulla versione e Rollback.

Il changelog del 25 settembre 2026 aggiunge un pezzo utile. I grafici di Workers Metrics mostrano ogni rilascio e ogni gradual deployment, e i rollback compaiono come eventi separati. Puoi così verificare se errori e latenza sono rientrati dopo il rollback.

Cosa il rollback non ripristina

Questa è la parte che conta, ed è dove un rollback "in un comando" smette di bastare.

Dati e risorse collegate. La pagina Rollbacks lo scrive in un riquadro di avvertimento: le risorse collegate al Worker non vengono modificate durante un rollback. Se la nuova versione ha cambiato la struttura dei dati, il codice vecchio può andare in errore su quei dati.

Migrazioni D1. La pagina Migrations di D1 elenca tre funzioni: creare un file di migrazione, elencare quelle non applicate, applicarle. Non c'è un comando per annullarne una. Se hai lanciato wrangler d1 migrations apply insieme al deploy, il rollback del Worker riporta il codice di prima su uno schema nuovo.

Rollback rifiutati. La documentazione elenca i casi in cui il rollback non è permesso. Il primo: tra la versione attiva e quella di destinazione c'è stato un cambio di ciclo di vita di una classe Durable Object. Il secondo: la versione di destinazione ha un binding verso un bucket R2, un namespace KV o una coda che non esistono più.

Segreti. Qui la documentazione è meno esplicita, e non voglio riempire il buco con una supposizione. Sappiamo che una versione cattura i binding e che un segreto è un tipo di binding. Sappiamo anche che i deployment non cancellano mai i segreti. Le pagine Rollbacks e Secrets però non dicono in chiaro se un rollback rimette il valore precedente di un segreto. Se hai ruotato una chiave e revocato la vecchia dal provider, tratta la chiave come un cambiamento a sé. Correggila con wrangler versions secret put, poi verifica.

Trigger. Route, domini e cron si applicano con wrangler triggers deploy, separati dalle versioni. La pagina Rollbacks non li cita tra le cose ripristinate. Se il deploy rotto li ha toccati, controllali a mano dopo il rollback.

Quando il problema sono i dati: Time Travel di D1

Per D1 il ripristino è Time Travel. È sempre attivo e non costa nulla in più. Ripristina un database a un minuto preciso degli ultimi 30 giorni sul piano Workers Paid, o degli ultimi 7 sul piano Free.

npx wrangler d1 time-travel info MIO_DB --timestamp="2026-10-25T14:00:00+01:00"
npx wrangler d1 time-travel restore MIO_DB --timestamp=UNIX_TIMESTAMP

La documentazione lo definisce un'operazione distruttiva: sovrascrive il database sul posto e cancella le query in corso. Tutto quello che è stato scritto dopo quel minuto sparisce, anche i dati buoni. Il restore restituisce un bookmark per annullare l'operazione. Ne ho scritto per esteso in Backup di D1: Time Travel, export e cosa fare prima che ti serva.

Per KV e R2 le pagine sulle versioni e sui rollback non citano un meccanismo equivalente. Se lì i dati contano, il piano di ripristino va pensato prima e non sta nel Worker.

Con cf invece di Wrangler

Cloudflare sta spingendo la nuova CLI cf, oggi in beta: ne ho parlato in Cloudflare spinge cf al posto di Wrangler. La pagina Projects della documentazione di cf mostra l'equivalente dei due passi. cf workers versions create carica una versione senza deployarla. cf workers deployments create la manda in produzione, con una strategia a percentuale:

cf workers versions create --message "nuovo checkout"
cf workers deployments create --worker my-worker --strategy percentage \
  --versions '[{"version_id":"<VERSION_ID>","percentage":100}]'

Nelle pagine lette oggi non ho trovato un comando cf dedicato al rollback. Lo stesso effetto si ottiene creando un deployment con la versione precedente al 100%. cf è in beta e comandi e flag possono cambiare prima della versione stabile. Per i comandi non ancora supportati la documentazione rimanda a npx wrangler.

Se a deployare è un agente

Un agente che lancia wrangler deploy a ogni modifica porta in produzione ogni errore al 100%. Due regole nel file di contesto del progetto, come AGENTS.md o CLAUDE.md, cambiano il profilo di rischio. L'agente usa wrangler versions upload con un --message che dice cosa cambia. Non lancia mai da solo d1 migrations apply, wrangler deploy su un cambio di classe Durable Object o wrangler secret put.

La checklist per portare in produzione un sito vibe-coded copre il resto: segreti, backup, permessi. Per i segreti in particolare c'è il pezzo su .env e chiavi API nei progetti vibe-coded.

Cosa conviene fare adesso

• Lancia npx wrangler deployments status e npx wrangler versions list sul tuo Worker. Annota l'ID della versione che oggi sai essere stabile.
• Dai un --message a ogni deploy e upload. In un rollback fatto di fretta, l'ID da solo non dice nulla.
• Separa i deploy che toccano lo schema D1 o le classi Durable Object da quelli che cambiano solo codice. Sono gli unici che il rollback non copre.
• Se servi asset con hash nel nome, configura la version affinity prima del primo gradual deployment, non dopo il primo 404.
• Prova il rollback su un Worker di staging prima che ti serva in produzione. Leggere la documentazione non sostituisce averlo fatto una volta.

Tornare indietro su Workers è davvero un comando, per il codice. Per tutto quello che il codice tocca, il piano va scritto prima del deploy.