Nesta página
Porque é que as atualizações do RabbitMQ correm mal?
"Muitas vezes, o que custa às empresas, ou o que elas esquecem, é que não fazem atualizações frequentes. Às vezes passam-se uns dois anos até fazerem uma atualização. E se tentam ir de onde estão diretamente para a versão mais recente, deparam-se com uma série de problemas imprevistos — porque o que deviam ter feito era atualizar passo a passo."
— Jeff Sogolov, engenheiro da AceMQ, sessão do projeto Lucidya, maio de 2025
Qual é o caminho de atualização obrigatório da 3.x para a 4.x?
rabbitmqctl enable_feature_flag allE a compatibilidade com o Erlang?
- 3.12 suporta, no mínimo, o Erlang 25.x
- 3.13 exige, no mínimo, o Erlang 26 (recomenda-se o 26.2)
- 4.x exige também, no mínimo, o Erlang 26.2
"É possível atualizar o Erlang diretamente do 25 para o 26.2. Quando estiver no 26.2, atualiza o RabbitMQ para a 3.13 — já tem o Erlang certo. Depois, da 3.13 para a 4.1, continua a aplicar-se a mesma versão do Erlang."
— Jeff Sogolov, engenheiro da AceMQ, sessão Lucidya, maio de 2025
Estratégia 1: rolling upgrade (in-place)
- Parar o nó 1 (apenas o serviço — não o sistema operativo)
- Atualizar o Erlang no nó 1 para a versão exigida
- Atualizar o RabbitMQ no nó 1 para a versão de destino
- Iniciar o serviço RabbitMQ no nó 1
- Confirmar que o nó 1 voltou a juntar-se ao cluster e está saudável
- Repetir nos nós 2 e 3
Estratégia 2: implementação blue-green
- Aprovisionar um novo cluster (green) com as versões de destino do RabbitMQ e do Erlang
- Configurar no cluster green um upstream de filas federadas que aponte para o cluster blue
- À medida que os consumers passam para o cluster green, a federation puxa automaticamente as mensagens do blue para o green
- Quando todos os consumers estiverem no green, passar os producers para o green
- Depois de passar os producers, esvaziar as mensagens que restem no blue com o plugin shovel
- Desativar o cluster blue
"O blue-green tem zero downtime. Pode fazê-lo a qualquer momento — não há modo de manutenção. O custo é ter dois clusters a funcionar ao mesmo tempo, o que algumas empresas não conseguem suportar, sobretudo on-prem. Mas em implementações na AWS, onde se podem criar novos clusters com facilidade, faz todo o sentido."
— Jeff Sogolov, engenheiro da AceMQ, sessão Lucidya, maio de 2025
Checklist pré-atualização
- Confirmar a versão atual do RabbitMQ e identificar o caminho de atualização necessário
- Consultar a matriz de compatibilidade do Erlang para as versões de destino e intermédias
- Ativar todas as feature flags na versão atual (rabbitmqctl enable_feature_flag all)
- Fazer cópia de segurança das definições do cluster (topologia, utilizadores, permissões) através da Management API
- Validar a atualização de ponta a ponta num ambiente de staging antes de tocar na produção
- Confirmar o comportamento dos health checks do load balancer com nós offline
- Testar em staging o comportamento de religação dos clientes com reinícios de nós simulados
- Agendar para a janela de menor tráfego, se usar rolling upgrade
- Ter o plano de rollback documentado antes de começar
Para uma visão mais ampla da preparação antes de se comprometer com uma janela, consulte a checklist de preparação para a migração do RabbitMQ.
O que muda no RabbitMQ 4.x e pode partir um ambiente 3.x
A maioria das atualizações da 3.x para a 4.x que correm mal falham numa de poucas alterações. Nenhuma é surpresa para quem lê as notas de versão da 4.0, mas qualquer uma passa facilmente despercebida num ambiente grande que cresceu com as convenções da 3.8 e da 3.9.
- O espelhamento de filas clássicas desapareceu. As filas clássicas espelhadas (as chaves de política
ha-modeeha-params) foram descontinuadas na 3.9 e removidas na 4.0. Um nó 4.x não espelha filas clássicas, pelo que qualquer fila que dependesse de uma política de HA para a replicação passa a ser uma fila de um único nó no momento em que a política deixa de se aplicar. É a única alteração que tem de ser tratada antes da atualização e não depois: migre cada fila espelhada para uma fila de quórum e, em seguida, elimine as políticas de HA.rabbitmq-diagnostics check_if_cluster_has_classic_queue_mirroring_policyindica se ainda resta alguma. Abordamos as vantagens e desvantagens no artigo filas clássicas vs. filas de quórum. - As filas transitórias não exclusivas foram descontinuadas. As filas não duráveis que não são exclusivas de uma ligação estão assinaladas como funcionalidade descontinuada e podem ser recusadas por configuração. Continuam a funcionar na 4.x, mas conte com declarar filas duráveis em todo o lado e usar filas exclusivas para estado genuinamente associado a uma ligação.
- O tipo de fila predefinido. Declarar uma fila sem
x-queue-typecontinua a dar uma fila clássica, a menos que o virtual host definadefault_queue_type. Defina-o comoquorumpor vhost para novas cargas de trabalho e garanta que o código cliente que declara filas passa umx-queue-typeexplícito, para que ninguém seja surpreendido por uma predefinição ao nível do vhost. - O AMQP 1.0 passou a protocolo nuclear. Na 4.0 deixa de ser necessário o plugin AMQP 1.0 separado; o 1.0 é implementado nativamente a par do 0-9-1 no mesmo listener. Os clientes 0-9-1 existentes não são afetados. As equipas que usavam o plugin antigo devem removê-lo da lista de plugins ativados, e as que querem o 1.0 devem passar para as bibliotecas cliente 1.0 mantidas em vez das legadas.
- Khepri como armazenamento de metadados. O Khepri, o substituto do Mnesia baseado em Raft, chegou como experimental na 3.13 e é suportado na 4.x, mas é opcional. Os nós continuam a usar o Mnesia depois da atualização até que ative deliberadamente a feature flag
khepri_db. Trate isso como uma alteração à parte, com a sua própria janela de testes, e não como efeito secundário da mudança de versão. - Todas as feature flags têm de ser ativadas primeiro. Um cluster 3.13 com qualquer feature flag estável ainda desativada não consegue juntar-se a um nó 4.x, e o nó 4.x recusa-se a arrancar contra ele. Ative tudo antes de o primeiro nó mudar.
- Os plugins e a interface de gestão. Os plugins compilados para a 3.x precisam de builds 4.x. O próprio plugin de gestão mantém-se, mas perde as vistas de espelhamento, e o plugin AMQP 1.0 deixa de ter efeito. Audite qualquer plugin da comunidade antes de partir do princípio de que funciona.
- MQTT 5. O suporte a MQTT 5 chegou na 3.13 e mantém-se na 4.x. Se vem da 3.12 ou anterior, os seus clientes MQTT ganham-no ao longo do caminho.
- Erlang. A 4.x exige o Erlang/OTP 26 ou posterior. Se os seus nós ainda estão no OTP 25, a atualização do Erlang faz-se como parte do rolling upgrade, um nó de cada vez. Leia a nossa nota sobre o fim de vida do Erlang 26 e o RabbitMQ antes de escolher uma versão de destino.
Devemos ficar na 3.13 ou atualizar para a 4.x?
A 3.13 é a última série 3.x. A sua janela de suporte da comunidade é curta e, quando fecha, deixa de haver patches de segurança upstream para qualquer versão 3.x. É essa a restrição real que determina a decisão.
Ficar na 3.13 é razoável num único caso: ter um acordo de suporte comercial ou alargado que faça o backport de correções de segurança para a versão que está a executar. Sem isso, um cluster 3.13 é uma contagem decrescente de CVE. O nosso suporte LTS alargado cobre da 3.8.x à 3.13.x com patches com backport, o que permite aos clientes manter séries mais antigas segundo um calendário que controlam, e não um ditado pelo calendário upstream. Dá tempo; não elimina a necessidade de planear a mudança.
Atualize quando estas quatro condições se verificarem:
- As filas clássicas espelhadas desapareceram e não resta nenhuma política de HA.
- Todas as feature flags estáveis estão ativadas em todos os nós.
- O Erlang está no OTP 26 ou posterior, ou está preparado para o mudar durante o rolling upgrade.
- As aplicações cliente usam versões de bibliotecas mantidas que se comportam corretamente com filas de quórum (tratamento correto de
x-delivery-limit, dead lettering e religação).
Atualize mais cedo do que o seu calendário de manutenção sugere se precisa de AMQP 1.0 sem o plugin, de MQTT 5 numa 3.x mais antiga ou das melhorias das filas de quórum da 4.x, que incluem prioridades de mensagens e um limite de entregas predefinido que impede as poison messages de circularem para sempre.
Se está entre a 3.8 e a 3.12, a resposta é a mesma, mas o caminho é mais longo: chegue primeiro à 3.13, estabilize e depois passe para a 4.x. Executamos as duas metades para os clientes, e o serviço de atualizações e patches de RabbitMQ tem esse âmbito.
Saber se ficar é seguro é uma questão diferente de saber se é possível: o RabbitMQ 3.x ainda é seguro? percorre, série a série, as datas de fim de vida e a exposição a CVE. Se ficar, o suporte LTS alargado para o RabbitMQ 3.x mantém a versão com patches enquanto a atualização aguarda uma janela.
O runbook de rolling upgrade que usamos
Esta é a sequência que seguimos nos clusters dos clientes. Pressupõe um cluster de três ou cinco nós, filas de quórum para tudo o que importa e clientes que voltam a ligar-se quando perdem a ligação.
- Inventário. Registe as versões, as versões do Erlang, os plugins ativados e todas as políticas. Execute
rabbitmq-diagnostics check_if_any_deprecated_features_are_usederabbitmq-diagnostics check_if_cluster_has_classic_queue_mirroring_policyem qualquer nó. Ambos têm de passar sem problemas antes de continuar. - Ative todas as feature flags estáveis.
rabbitmqctl enable_feature_flag allnum nó aplica-se a todo o cluster. Confirme comrabbitmqctl list_feature_flags; qualquer flag aindadisabledbloqueia a atualização. - Converta as filas clássicas espelhadas em filas de quórum, fluxo a fluxo. As filas de quórum não podem ser convertidas in-place. Para cada fluxo, declare a fila de quórum, redirecione os consumers, redirecione os producers, esvazie a fila antiga e elimine-a. Faça-o aplicação a aplicação, para que um erro afete um fluxo e não o ambiente inteiro.
- Verifique a versão de destino do Erlang. Confirme que o pacote OTP 26 ou posterior está disponível em todos os nós e que é a versão com que o seu build 4.x foi testado.
- Exporte as definições e faça uma cópia de segurança.
rabbitmqctl export_definitions, mais uma cópia de segurança do diretório de dados ao nível do sistema de ficheiros em todos os nós. A exportação das definições é a base para reconstruir se a fronteira de rollback for ultrapassada. - Atualize um nó de cada vez. Antes de parar um nó, execute
rabbitmq-upgrade await_online_quorum_plus_onepara que nenhuma fila de quórum perca a maioria enquanto este nó estiver fora. Depois,rabbitmq-upgrade draincoloca o nó em modo de manutenção, fecha de forma ordenada as ligações dos clientes e transfere a liderança das filas de quórum. Pare o serviço, atualize o Erlang se necessário, atualize o RabbitMQ, inicie-o e confirme que voltou a juntar-se ao cluster. - Aguarde que os membros das filas de quórum recuperem o atraso.
rabbitmq-queues quorum_status <queue>nas filas mais carregadas, ourabbitmq-diagnostics check_if_node_is_quorum_criticalno próximo nó que pretende parar. Não avance para o nó seguinte até esta verificação passar. - Verifique que os clientes voltaram a ligar-se. O número de ligações na interface de gestão deve voltar ao valor de referência no nó atualizado. Se uma biblioteca cliente não voltar a ligar-se, corrija-a já, antes do nó seguinte.
- Repita para cada nó restante. Durante esta janela, o cluster funciona com versões mistas 3.13 e 4.x. Não altere políticas, não acrescente filas nem ative nada de novo até o último nó estar concluído.
- Ative as novas feature flags da 4.x. Depois de atualizado o último nó, execute novamente
rabbitmqctl enable_feature_flag all. Esta é a fronteira de rollback: assim que uma feature flag exclusiva da 4.x é ativada, deixa de haver caminho de downgrade. Tudo o que vem antes deste passo pode ser revertido restaurando um nó para a 3.13.
rabbitmqctl enable_feature_flag all
rabbitmq-upgrade await_online_quorum_plus_one
rabbitmq-upgrade drainO blue-green é a alternativa quando o cluster é suficientemente pequeno para ser reconstruído, a exportação das definições é fiável e é possível mudar os clientes por DNS ou load balancer. Dá-lhe um cluster 4.x limpo e um cluster 3.13 intacto para onde regressar. Preferimo-lo para clusters que acumularam anos de políticas não documentadas.
Em qualquer dos casos, o suporte cobre a janela de atualização com resposta P1 em 15 minutos, o que importa sobretudo entre o passo 6 e o passo 10.
Perguntas frequentes
Posso atualizar diretamente do RabbitMQ 3.13 para o 4.x?
Sim. É suportado um rolling upgrade da 3.13.x para a 4.0.x, desde que todas as feature flags estáveis estejam ativadas, não restem políticas de espelhamento de filas clássicas e o Erlang esteja no OTP 26 ou posterior. Se está na 3.12 ou anterior, não pode saltar diretamente para a 4.x; atualize primeiro para a 3.13, ative as respetivas feature flags e só depois continue. O motivo é que os nós 4.x só se juntam a clusters em que o conjunto de feature flags da 3.13 esteja totalmente ativado, e as séries mais antigas não conseguem cumprir esse requisito.
Posso continuar no RabbitMQ 3.x?
Pode, mas só em segurança com um acordo de suporte que faça o backport de correções de segurança, porque os patches upstream para a 3.x terminam com a janela de suporte da comunidade da 3.13. O nosso suporte LTS alargado cobre da 3.8.x à 3.13.x com patches de CVE com backport, precisamente para esta situação. Ficar faz sentido quando uma migração de clientes, um congelamento por motivos de conformidade ou uma conversão de filas precisa de mais tempo do que o calendário upstream permite. Não faz sentido como estado permanente; planeie a passagem para a 4.x ao seu próprio ritmo.
Como se atualiza o RabbitMQ sem downtime?
Com um rolling upgrade, um nó de cada vez. Ative todas as feature flags, remova as filas clássicas espelhadas, exporte as definições e, depois, para cada nó, execute rabbitmq-upgrade await_online_quorum_plus_one, faça o drain, atualize o Erlang e o RabbitMQ, reinicie e aguarde que os membros das filas de quórum recuperem o atraso antes de passar ao nó seguinte. Os clientes que voltam a ligar-se quando perdem a ligação veem uma breve religação, não uma indisponibilidade. O blue-green, com um novo cluster 4.x e um cutover dos clientes, é a opção quando o cluster existente está demasiado emaranhado para ser atualizado in-place.
O RabbitMQ 4 exige o Erlang 26?
Sim. O RabbitMQ 4.x exige o Erlang/OTP 26 ou posterior. Se os seus nós 3.13 já estão no OTP 26, o passo do Erlang não implica nada; se estão no OTP 25, atualize o Erlang em cada nó durante a mesma janela de rolling upgrade que o pacote do RabbitMQ. Consulte a tabela de compatibilidade para o patch 4.x exato que vai instalar, já que as versões 4.x mais recentes sobem o mínimo. O nosso artigo sobre o fim de vida do Erlang 26 explica o que isso significa para os calendários de suporte.