In questa pagina
Perché gli aggiornamenti di RabbitMQ vanno storti?
"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
Qual è il percorso di aggiornamento obbligato dalla 3.x alla 4.x?
rabbitmqctl enable_feature_flag allE la compatibilità con Erlang?
- 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)
- Fermate il nodo 1 (solo il servizio, non il sistema operativo)
- Aggiornate Erlang sul nodo 1 alla versione richiesta
- Aggiornate RabbitMQ sul nodo 1 alla versione di destinazione
- Avviate il servizio RabbitMQ sul nodo 1
- Verificate che il nodo 1 sia rientrato nel cluster e sia in salute
- Ripetete per i nodi 2 e 3
Strategia 2: deployment blue-green
- Predisponete un nuovo cluster (green) con le versioni di destinazione di RabbitMQ ed Erlang
- Configurate sul cluster green un upstream di federated queue che punti al cluster blue
- Man mano che i consumer vengono spostati sul cluster green, la federation trasferisce automaticamente i messaggi da blue a green
- Quando tutti i consumer sono su green, spostate i producer su green
- Una volta spostati i producer, svuotate i messaggi rimasti su blue con il plugin shovel
- Dismettete il cluster blue
"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
Checklist pre-aggiornamento
- 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
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-modeeha-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_policyindica 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-typeproduce ancora una coda classica, a meno che il virtual host non impostidefault_queue_type. Impostatelo aquorumper vhost per i nuovi workload, e assicuratevi che il codice client che dichiara le code passi un valore esplicito dix-queue-typecosì 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:
- Le code classiche in mirroring non ci sono più e non restano policy HA.
- Ogni feature flag stabile è abilitato su ogni nodo.
- Erlang è su OTP 26 o successivo, oppure siete pronti ad aggiornarlo durante il rolling upgrade.
- 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.
- Inventario. Registrate versioni, versioni di Erlang, plugin abilitati e tutte le policy. Eseguite
rabbitmq-diagnostics check_if_any_deprecated_features_are_usederabbitmq-diagnostics check_if_cluster_has_classic_queue_mirroring_policysu un nodo qualsiasi. Entrambi i controlli devono dare esito pulito prima di proseguire. - Abilitate tutti i feature flag stabili.
rabbitmqctl enable_feature_flag allsu un nodo si applica all'intero cluster. Verificate conrabbitmqctl list_feature_flags; qualsiasi flag ancoradisabledblocca l'aggiornamento. - 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.
- 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.
- Esportate le definizioni ed eseguite un backup.
rabbitmqctl export_definitionspiù 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. - Aggiornate un nodo alla volta. Prima di fermare un nodo, eseguite
rabbitmq-upgrade await_online_quorum_plus_onein modo che nessuna coda quorum perda la maggioranza mentre il nodo è fuori servizio. Poirabbitmq-upgrade drainmette 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. - Attendete che i membri delle code quorum si riallineino.
rabbitmq-queues quorum_status <queue>sulle code più trafficate, oppurerabbitmq-diagnostics check_if_node_is_quorum_criticalsul nodo successivo che intendete fermare. Non passate al nodo successivo finché questo controllo non dà esito positivo. - 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.
- 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.
- Abilitate i nuovi feature flag della 4.x. Dopo l'aggiornamento dell'ultimo nodo, eseguite
rabbitmqctl enable_feature_flag alldi 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 drainIl 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.