RabbitMQ

Aggiornare RabbitMQ da 3.x a 4.x senza downtime: rolling o blue-green

Scott Sternloff

Di Scott Sternloff, Enterprise Architect senior

LinkedIn · Aggiornato il

3.13EOL4.xCURRENTNo DowntimeRolling & Blue-Green Upgrade
In questa pagina
L'aggiornamento di RabbitMQ è una di quelle operazioni che dovrebbero essere semplici ma che regolarmente colgono i team impreparati. I vincoli sul percorso di versione non sono ovvi, la dipendenza da Erlang aggiunge un'altra variabile e il costo di un errore in produzione è alto.
Questo articolo illustra le due strategie che funzionano, rolling upgrade e deployment blue-green, e i passaggi preliminari che la maggior parte dei team trascura, tra cui l'abilitazione dei feature flag e la verifica della compatibilità delle versioni di Erlang.

Perché gli aggiornamenti di RabbitMQ vanno storti?

Lo scenario di errore più comune è quello di un team che non aggiorna da un anno o più, decide di passare all'ultima versione e salta i passaggi intermedi richiesti dal percorso di aggiornamento.

"Spesso il problema delle aziende, o ciò che dimenticano, è che non aggiornano con regolarità. A volte passano un paio d'anni prima di un aggiornamento. E se cercano di passare direttamente da dove sono all'ultima versione, incontrano una serie di problemi imprevisti, perché avrebbero dovuto aggiornare un passo alla volta."

— Jeff Sogolov, ingegnere AceMQ, sessione di lavoro con Lucidya, maggio 2025

RabbitMQ ha un percorso di aggiornamento definito. Non si possono saltare versioni major. Se siete sulla 3.12, dovete aggiornare alla 3.13 prima di poter passare alla 4.x. Tentare il salto diretto causa instabilità del cluster e problemi di compatibilità difficili da diagnosticare.

Qual è il percorso di aggiornamento obbligato dalla 3.x alla 4.x?

Il percorso di aggiornamento delle versioni è documentato da Broadcom e va seguito con precisione. La regola chiave: si può aggiornare una sola versione major alla volta.
Dalla 3.12 → si deve passare alla 3.13 → poi alla 4.x. Non si può passare direttamente dalla 3.12 alla 4.1. Se siete più indietro, sulla 3.10 o sulla 3.11, dovete attraversare in sequenza ogni versione major.
Ogni passaggio richiede inoltre, prima di aggiornare, di abilitare tutti i feature flag sulla versione corrente:
rabbitmqctl enable_feature_flag all
Non abilitare i feature flag prima di un salto di versione è una causa frequente di aggiornamenti falliti. Verificate sempre che tutti i flag risultino abilitati prima di passare alla versione successiva.

E la compatibilità con Erlang?

Ogni versione di RabbitMQ specifica una versione minima e una massima di Erlang supportate. Aggiornare RabbitMQ senza aver prima portato Erlang alla versione richiesta fa fallire la nuova versione di RabbitMQ.
Checkpoint chiave di Erlang per il percorso 3.12 → 3.13 → 4.x:
  • 3.12 supporta come minimo Erlang 25.x
  • 3.13 richiede almeno Erlang 26 (consigliata la 26.2)
  • 4.x richiede anch'essa almeno Erlang 26.2

"Potete aggiornare Erlang direttamente dalla 25 alla 26.2. Una volta sulla 26.2, aggiornate RabbitMQ alla 3.13: avete già l'Erlang giusto. Poi dalla 3.13 alla 4.1 vale ancora la stessa versione di Erlang."

— Jeff Sogolov, ingegnere AceMQ, sessione con Lucidya, maggio 2025

Strategia 1: rolling upgrade (in-place)

Un rolling upgrade aggiorna i nodi del cluster esistente uno alla volta, senza creare un nuovo cluster. Si ferma un nodo, si aggiorna RabbitMQ (ed Erlang se necessario), lo si riavvia e si passa al nodo successivo.
Come funziona:
  1. Fermate il nodo 1 (solo il servizio, non il sistema operativo)
  2. Aggiornate Erlang sul nodo 1 alla versione richiesta
  3. Aggiornate RabbitMQ sul nodo 1 alla versione di destinazione
  4. Avviate il servizio RabbitMQ sul nodo 1
  5. Verificate che il nodo 1 sia rientrato nel cluster e sia in salute
  6. Ripetete per i nodi 2 e 3
Durante il rolling upgrade il cluster esegue temporaneamente versioni miste. È supportato all'interno di una singola versione major, ma non oltre il confine tra versioni major. Eseguite i rolling upgrade nei periodi di traffico ridotto: aggiornare sotto carico elevato aumenta il rischio, perché la replica delle code quorum e la sincronizzazione dei messaggi generano overhead aggiuntivo.
Pro: Nessuna nuova infrastruttura, orchestrazione più semplice, usa la membership del cluster esistente. Contro: I brevi riavvii di ciascun nodo interrompono le connessioni; va eseguito in periodi di traffico ridotto.

Strategia 2: deployment blue-green

Un deployment blue-green crea un cluster completamente nuovo (green) accanto a quello esistente (blue), migra il traffico verso il nuovo cluster tramite federation e dismette quello vecchio a transizione completata.
Come funziona:
  1. Predisponete un nuovo cluster (green) con le versioni di destinazione di RabbitMQ ed Erlang
  2. Configurate sul cluster green un upstream di federated queue che punti al cluster blue
  3. Man mano che i consumer vengono spostati sul cluster green, la federation trasferisce automaticamente i messaggi da blue a green
  4. Quando tutti i consumer sono su green, spostate i producer su green
  5. Una volta spostati i producer, svuotate i messaggi rimasti su blue con il plugin shovel
  6. Dismettete il cluster blue
Distinzione chiave: Usate le codefederate, non gli exchange federati. Con le code federate, quando un consumer è presente sul cluster downstream (green), i messaggi vengono prelevati dal cluster upstream (blue) e consumati lì: non vengono conservati su entrambi i lati.

"Il blue-green significa zero downtime. Potete farlo in qualsiasi momento, non c'è una modalità di manutenzione. Il costo è avere due cluster attivi contemporaneamente, cosa che alcune aziende non possono permettersi, soprattutto on-prem. Ma per i deployment su AWS, dove si possono creare nuovi cluster facilmente, ha molto senso."

— Jeff Sogolov, ingegnere AceMQ, sessione con Lucidya, maggio 2025

Pro: Migrazione senza downtime, eseguibile in qualsiasi momento. Contro: Richiede temporaneamente il doppio dell'infrastruttura e più passaggi di configurazione.

Obiettivi di risposta da 15 minuti, in base al piano. Ingegneri senior dedicati.

Contattateci

Checklist pre-aggiornamento

Prima di avviare qualsiasi aggiornamento di RabbitMQ:
  • Verificate la versione attuale di RabbitMQ e individuate il percorso di aggiornamento richiesto
  • Consultate la matrice di compatibilità di Erlang per la versione di destinazione e quelle intermedie
  • Abilitate tutti i feature flag sulla versione corrente (rabbitmqctl enable_feature_flag all)
  • Eseguite il backup delle definizioni del cluster (topologia, utenti, permessi) tramite la Management API
  • Validate l'aggiornamento end-to-end in staging prima di toccare la produzione
  • Verificate il comportamento degli health check del load balancer con i nodi offline
  • Testate in staging il comportamento di riconnessione dei client simulando riavvii dei nodi
  • Se usate il rolling upgrade, pianificatelo nella finestra con il traffico più basso
  • Documentate un piano di rollback prima di iniziare
Gli aggiornamenti di RabbitMQ su più versioni, soprattutto il salto dalla 3.x alla 4.x, sono tra i tipi di intervento più frequenti che gestiamo. Se volete aiuto per definire il perimetro dell'aggiornamento, progettare l'approccio di migrazione o affidarne l'esecuzione a un ingegnere AceMQ durante la vostra finestra di manutenzione, contattate il nostro team di supporto RabbitMQ.

Per una visione più ampia della preparazione prima di impegnarvi su una finestra, consultate la checklist di preparazione alla migrazione di RabbitMQ.

Cosa cambia in RabbitMQ 4.x che può rompere un ambiente 3.x

La maggior parte degli aggiornamenti dalla 3.x alla 4.x che vanno storti inciampa su uno di un breve elenco di cambiamenti. Nessuno è una sorpresa se si leggono le release notes della 4.0, ma ciascuno è facile da trascurare in un ambiente esteso cresciuto con le convenzioni della 3.8 e della 3.9.

  • Il mirroring delle code classiche non esiste più. Le code classiche in mirroring (chiavi di policy ha-mode e ha-params) sono state deprecate nella 3.9 e rimosse nella 4.0. Un nodo 4.x non esegue il mirroring delle code classiche, quindi ogni coda che si affidava a una policy HA per la replica diventa una coda su singolo nodo nel momento in cui la policy smette di applicarsi. È l'unico cambiamento che va gestito prima dell'aggiornamento e non dopo: migrate ogni coda in mirroring a una coda quorum, poi eliminate le policy HA. rabbitmq-diagnostics check_if_cluster_has_classic_queue_mirroring_policy indica se ne restano. Approfondiamo i compromessi nel nostro articolo code classiche vs code quorum.
  • Le code transitorie non esclusive sono deprecate. Le code non durevoli che non sono esclusive di una connessione sono contrassegnate come funzionalità deprecata e possono essere vietate tramite configurazione. Funzionano ancora nella 4.x, ma pianificate di dichiarare ovunque code durevoli e di usare code esclusive per lo stato davvero legato alla singola connessione.
  • Il tipo di coda predefinito. Dichiarare una coda senza x-queue-type produce ancora una coda classica, a meno che il virtual host non imposti default_queue_type. Impostatelo a quorum per vhost per i nuovi workload, e assicuratevi che il codice client che dichiara le code passi un valore esplicito di x-queue-type così che nessuno venga sorpreso da un default a livello di vhost.
  • AMQP 1.0 è un protocollo core. Nella 4.0 il plugin AMQP 1.0 separato non serve più: la 1.0 è implementata nativamente accanto alla 0-9-1 sullo stesso listener. I client 0-9-1 esistenti non sono interessati. I team che usavano il vecchio plugin dovrebbero rimuoverlo dall'elenco dei plugin abilitati, e chi vuole usare la 1.0 dovrebbe passare alle librerie client 1.0 mantenute anziché a quelle legacy.
  • Khepri come metadata store. Khepri, il sostituto di Mnesia basato su Raft, è stato introdotto come sperimentale nella 3.13 ed è supportato nella 4.x, ma è opzionale. Dopo l'aggiornamento i nodi continuano a usare Mnesia finché non abilitate deliberatamente il feature flag khepri_db. Trattatelo come una modifica separata con una propria finestra di test, non come un effetto collaterale del cambio di versione.
  • Tutti i feature flag devono essere abilitati prima. Un cluster 3.13 con anche un solo feature flag stabile ancora disabilitato non può unirsi a un nodo 4.x, e il nodo 4.x si rifiuta di avviarsi con esso. Abilitate tutto prima che si muova il primo nodo.
  • Plugin e management UI. I plugin compilati per la 3.x richiedono build per la 4.x. Il plugin di management viene mantenuto, ma perde le viste sul mirroring e il plugin AMQP 1.0 diventa inutile. Verificate ogni plugin della community prima di dare per scontato che funzioni.
  • MQTT 5. Il supporto di MQTT 5 è arrivato con la 3.13 e prosegue nella 4.x. Se venite dalla 3.12 o precedenti, i vostri client MQTT lo ottengono lungo il percorso.
  • Erlang. La 4.x richiede Erlang/OTP 26 o successivo. Se i vostri nodi sono ancora su OTP 25, l'aggiornamento di Erlang avviene nell'ambito del rolling upgrade, un nodo alla volta. Prima di scegliere la versione di destinazione, leggete la nostra nota su fine vita di Erlang 26 e RabbitMQ.

Conviene restare sulla 3.13 o aggiornare alla 4.x?

La 3.13 è l'ultima serie 3.x. La sua finestra di supporto della community è breve e, una volta chiusa, non esistono patch di sicurezza upstream per nessuna versione 3.x. È questo il vincolo reale che guida la decisione.

Restare sulla 3.13 è ragionevole in un solo caso: avete un accordo di supporto commerciale o esteso che porta in backport le correzioni di sicurezza sulla versione in uso. Senza, un cluster 3.13 è un conto alla rovescia verso la prossima CVE. Il nostro supporto LTS esteso copre dalla 3.8.x alla 3.13.x con patch in backport, ed è ciò che consente ai clienti di usare serie più vecchie secondo un calendario che controllano loro, non uno dettato dall'upstream. Fa guadagnare tempo, ma non elimina la necessità di pianificare il passaggio.

Aggiornate quando tutte e quattro queste condizioni sono vere:

  1. Le code classiche in mirroring non ci sono più e non restano policy HA.
  2. Ogni feature flag stabile è abilitato su ogni nodo.
  3. Erlang è su OTP 26 o successivo, oppure siete pronti ad aggiornarlo durante il rolling upgrade.
  4. Le applicazioni client usano versioni di libreria mantenute che si comportano correttamente con le code quorum (gestione corretta di x-delivery-limit, dead lettering e riconnessione).

Aggiornate prima di quanto suggerisca il vostro calendario di manutenzione se vi servono AMQP 1.0 senza plugin, MQTT 5 su una 3.x più vecchia o i miglioramenti delle code quorum della 4.x, tra cui le priorità dei messaggi e un delivery limit predefinito che impedisce ai poison message di circolare all'infinito.

Se siete su una versione dalla 3.8 alla 3.12, la risposta è la stessa ma il percorso è più lungo: arrivate prima alla 3.13, stabilizzate, poi passate alla 4.x. Gestiamo entrambe le metà per i nostri clienti, e il servizio di aggiornamenti e patch RabbitMQ è strutturato proprio così.

Che restare sia sicuro è una questione distinta dal fatto che sia possibile: RabbitMQ 3.x è ancora sicuro da usare? esamina le date di fine vita e l'esposizione alle CVE serie per serie. Se restate, il supporto LTS esteso per RabbitMQ 3.x mantiene la versione aggiornata con le patch mentre l'aggiornamento attende una finestra.

Il runbook di rolling upgrade che usiamo

È la sequenza che seguiamo sui cluster dei clienti. Presuppone un cluster a tre o cinque nodi, code quorum per tutto ciò che conta e client che si riconnettono in caso di perdita della connessione.

  1. Inventario. Registrate versioni, versioni di Erlang, plugin abilitati e tutte le policy. Eseguite rabbitmq-diagnostics check_if_any_deprecated_features_are_used e rabbitmq-diagnostics check_if_cluster_has_classic_queue_mirroring_policy su un nodo qualsiasi. Entrambi i controlli devono dare esito pulito prima di proseguire.
  2. Abilitate tutti i feature flag stabili. rabbitmqctl enable_feature_flag all su un nodo si applica all'intero cluster. Verificate con rabbitmqctl list_feature_flags; qualsiasi flag ancora disabled blocca l'aggiornamento.
  3. Convertite le code classiche in mirroring in code quorum, flusso per flusso. Le code quorum non possono essere convertite in-place. Per ogni flusso, dichiarate la coda quorum, reindirizzate i consumer, reindirizzate i producer, svuotate la vecchia coda ed eliminatela. Procedete applicazione per applicazione, così che un errore riguardi un solo flusso e non l'intero ambiente.
  4. Verificate la versione di Erlang di destinazione. Verificate che il pacchetto OTP 26 o successivo sia disponibile su ogni nodo e che sia la versione con cui è stata testata la vostra build 4.x.
  5. Esportate le definizioni ed eseguite un backup. rabbitmqctl export_definitions più un backup a livello di filesystem della directory dei dati su ogni nodo. L'export delle definizioni è ciò da cui ricostruire se si supera il confine del rollback.
  6. Aggiornate un nodo alla volta. Prima di fermare un nodo, eseguite rabbitmq-upgrade await_online_quorum_plus_one in modo che nessuna coda quorum perda la maggioranza mentre il nodo è fuori servizio. Poi rabbitmq-upgrade drain mette il nodo in modalità manutenzione, chiude in modo ordinato le connessioni dei client e trasferisce altrove la leadership delle code quorum. Fermate il servizio, aggiornate Erlang se necessario, aggiornate RabbitMQ, avviatelo e verificate che sia rientrato nel cluster.
  7. Attendete che i membri delle code quorum si riallineino. rabbitmq-queues quorum_status <queue> sulle code più trafficate, oppure rabbitmq-diagnostics check_if_node_is_quorum_critical sul nodo successivo che intendete fermare. Non passate al nodo successivo finché questo controllo non dà esito positivo.
  8. Verificate che i client si siano riconnessi. Il numero di connessioni nella management UI dovrebbe tornare ai valori abituali sul nodo aggiornato. Se una libreria client non si riconnette, correggetela subito, prima del nodo successivo.
  9. Ripetete per ciascuno dei nodi rimanenti. Durante questa finestra il cluster esegue versioni miste 3.13 e 4.x. Non modificate policy, non aggiungete code e non abilitate nulla di nuovo finché l'ultimo nodo non è completato.
  10. Abilitate i nuovi feature flag della 4.x. Dopo l'aggiornamento dell'ultimo nodo, eseguite rabbitmqctl enable_feature_flag all di nuovo. È il confine del rollback: una volta abilitato un feature flag esclusivo della 4.x non esiste un percorso di downgrade. Tutto ciò che precede questo passaggio può essere annullato riportando un nodo alla 3.13.
rabbitmqctl enable_feature_flag all
rabbitmq-upgrade await_online_quorum_plus_one
rabbitmq-upgrade drain

Il blue-green è l'alternativa quando il cluster è abbastanza piccolo da essere ricostruito, l'export delle definizioni è affidabile e potete permettervi di spostare i client tramite DNS o load balancer. Offre un cluster 4.x pulito e un cluster 3.13 intatto su cui ripiegare. Lo preferiamo per i cluster che hanno accumulato anni di policy non documentate.

In entrambi i casi, il supporto copre la finestra di aggiornamento con una risposta P1 entro 15 minuti, che conta soprattutto tra il passaggio 6 e il passaggio 10.

Domande frequenti

Si può aggiornare direttamente da RabbitMQ 3.13 a 4.x?

Sì. Un rolling upgrade dalla 3.13.x alla 4.0.x è supportato, a condizione che tutti i feature flag stabili siano abilitati, che non restino policy di mirroring delle code classiche e che Erlang sia su OTP 26 o successivo. Se siete sulla 3.12 o precedenti non potete saltare direttamente alla 4.x: aggiornate prima alla 3.13, abilitatene i feature flag e poi proseguite. Il motivo è che i nodi 4.x si uniscono solo a cluster in cui l'insieme dei feature flag della 3.13 è completamente abilitato, cosa che le serie precedenti non possono soddisfare.

Si può restare su RabbitMQ 3.x?

Sì, ma in sicurezza solo con un accordo di supporto che porti in backport le correzioni di sicurezza, perché le patch upstream per la 3.x terminano con la finestra di supporto della community della 3.13. Il nostro supporto LTS esteso copre dalla 3.8.x alla 3.13.x con patch delle CVE in backport, proprio per questa situazione. Restare ha senso quando una migrazione dei client, un blocco per motivi di conformità o una conversione delle code richiedono più tempo di quanto consenta il calendario upstream. Non ha senso come condizione permanente: pianificate il passaggio alla 4.x secondo i vostri tempi.

Come si aggiorna RabbitMQ senza downtime?

Con un rolling upgrade, un nodo alla volta. Abilitate tutti i feature flag, rimuovete le code classiche in mirroring, esportate le definizioni, poi per ogni nodo eseguite rabbitmq-upgrade await_online_quorum_plus_one, mettetelo in drain, aggiornate Erlang e RabbitMQ, riavviate e attendete che i membri delle code quorum si riallineino prima di toccare il nodo successivo. I client che si riconnettono in caso di perdita della connessione vedono una breve riconnessione, non un disservizio. Il blue-green, con un nuovo cluster 4.x e un cutover dei client, è l'opzione da scegliere quando il cluster esistente è troppo complesso da aggiornare in-place.

RabbitMQ 4 richiede Erlang 26?

Sì. RabbitMQ 4.x richiede Erlang/OTP 26 o successivo. Se i vostri nodi 3.13 sono già su OTP 26, il passaggio di Erlang non richiede interventi; se sono su OTP 25, aggiornate Erlang su ogni nodo nella stessa finestra di rolling del pacchetto RabbitMQ. Verificate la tabella di compatibilità per l'esatta patch release 4.x che state installando, perché le release 4.x successive alzano il requisito minimo. Il nostro articolo sulla fine vita di Erlang 26 spiega cosa significa per le tempistiche di supporto.

Consulenza gratuita

Fate esaminare a un esperto il vostro cluster RabbitMQ

Che stiate risolvendo un incidente in produzione, pianificando una migrazione o cercando un secondo parere sulla vostra architettura, il nostro team è pronto. Nessun discorso commerciale, solo risposte.

Scriveteci