Nesta página
Por que os upgrades do RabbitMQ dão errado?
"Muitas vezes, a dificuldade das empresas, ou o que elas esquecem, é que não fazem upgrades com frequência. Às vezes leva alguns anos para fazer um upgrade. E, se elas tentam ir de onde estão direto para a versão mais recente, aparece uma série de problemas imprevistos — porque o que deveriam ter feito era o upgrade passo a passo."
— Jeff Sogolov, engenheiro da AceMQ, sessão do projeto com a Lucidya, maio de 2025
Qual é o caminho de upgrade obrigatório da 3.x para a 4.x?
rabbitmqctl enable_feature_flag allE a compatibilidade com o Erlang?
- A 3.12 suporta, no mínimo, o Erlang 25.x
- A 3.13 exige, no mínimo, o Erlang 26 (26.2 recomendado)
- A 4.x também exige, no mínimo, o Erlang 26.2
"Dá para atualizar o Erlang do 25 direto para o 26.2. Quando você está no 26.2, faz o upgrade do RabbitMQ para a 3.13 — você já tem o Erlang certo. Depois, da 3.13 para a 4.1, a mesma versão do Erlang continua valendo."
— Jeff Sogolov, engenheiro da AceMQ, sessão com a Lucidya, maio de 2025
Estratégia 1: rolling upgrade (in-place)
- Pare o nó 1 (apenas o serviço — não o sistema operacional)
- Atualize o Erlang no nó 1 para a versão exigida
- Atualize o RabbitMQ no nó 1 para a versão de destino
- Inicie o serviço do RabbitMQ no nó 1
- Confirme que o nó 1 voltou ao cluster e está saudável
- Repita para os nós 2 e 3
Estratégia 2: implantação blue-green
- Provisione um novo cluster (green) na versão de destino do RabbitMQ e do Erlang
- Configure um upstream de fila federada no cluster green apontando para o cluster blue
- À medida que os consumers são movidos para o cluster green, a federation puxa automaticamente as mensagens do blue para o green
- Quando todos os consumers estiverem no green, mova os producers para o green
- Depois de mover os producers, drene as mensagens restantes do blue usando o plugin shovel
- Desative o cluster blue
"O blue-green tem zero downtime. Você pode fazer a qualquer momento — não existe modo de manutenção. O custo é ter dois clusters rodando ao mesmo tempo, o que algumas empresas não podem bancar, principalmente on-premises. Mas, em implantações na AWS, onde dá para subir novos clusters com facilidade, faz muito sentido."
— Jeff Sogolov, engenheiro da AceMQ, sessão com a Lucidya, maio de 2025
Checklist pré-upgrade
- Confirme a versão atual do RabbitMQ e identifique o caminho de upgrade necessário
- Consulte a matriz de compatibilidade do Erlang para as versões de destino e intermediárias
- Habilite todas as feature flags na versão atual (rabbitmqctl enable_feature_flag all)
- Faça backup das definições do cluster (topologia, usuários, permissões) pela Management API
- Valide o upgrade de ponta a ponta no ambiente de staging antes de mexer em produção
- Confirme o comportamento do health check do load balancer com nós fora do ar
- Teste o comportamento de reconexão dos clientes em staging simulando reinícios de nós
- Agende para a janela de menor tráfego se for usar rolling upgrade
- Tenha um plano de rollback documentado antes de começar
Para uma visão mais ampla de prontidão antes de se comprometer com uma janela, veja o checklist de prontidão para migração do RabbitMQ.
O que muda no RabbitMQ 4.x e pode quebrar um ambiente 3.x
A maioria dos upgrades da 3.x para a 4.x que dão errado falha em uma de poucas mudanças. Nenhuma delas é surpresa para quem lê as notas de versão da 4.0, mas cada uma é fácil de deixar passar em um ambiente grande que cresceu com as convenções da 3.8 e da 3.9.
- O espelhamento de filas clássicas acabou. As filas clássicas espelhadas (as chaves de política
ha-modeeha-params) foram depreciadas na 3.9 e removidas na 4.0. Um nó 4.x não espelha filas clássicas, então qualquer fila que dependia de uma política de HA para replicação vira uma fila de um único nó no momento em que a política deixa de ser aplicada. Essa é a única mudança que precisa ser tratada antes do upgrade, e não depois: migre cada fila espelhada para uma fila de quórum e depois exclua as políticas de HA.rabbitmq-diagnostics check_if_cluster_has_classic_queue_mirroring_policyinforma se ainda resta alguma. Tratamos dos prós e contras no nosso post filas clássicas vs. filas de quórum. - As filas transitórias não exclusivas estão depreciadas. Filas não duráveis que não são exclusivas de uma conexão são sinalizadas como recurso depreciado e podem ser bloqueadas por configuração. Elas ainda funcionam na 4.x, mas planeje declarar filas duráveis em todos os lugares e usar filas exclusivas para estado realmente vinculado a uma conexão.
- O tipo de fila padrão. Declarar uma fila sem
x-queue-typeainda gera 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 passe umx-queue-typeexplícito, para que ninguém seja surpreendido por um padrão no nível do vhost. - O AMQP 1.0 é um protocolo do núcleo. Na 4.0, o plugin separado de AMQP 1.0 deixou de ser necessário; o 1.0 é implementado nativamente junto com o 0-9-1, no mesmo listener. Os clientes 0-9-1 existentes não são afetados. As equipes que usavam o plugin antigo devem removê-lo da lista de plugins habilitados, e as que querem o 1.0 devem migrar para as bibliotecas cliente 1.0 mantidas, e não para as legadas.
- O Khepri como armazenamento de metadados. O Khepri, substituto do Mnesia baseado em Raft, foi lançado como experimental na 3.13 e tem suporte na 4.x, mas é opcional. Os nós continuam usando o Mnesia depois do upgrade até você habilitar deliberadamente a feature flag
khepri_db. Trate isso como uma mudança separada, com sua própria janela de testes, e não como efeito colateral da troca de versão. - Todas as feature flags precisam ser habilitadas antes. Um cluster 3.13 com qualquer feature flag estável ainda desabilitada não aceita um nó 4.x, e o nó 4.x se recusa a iniciar nesse cluster. Habilite tudo antes de o primeiro nó ser atualizado.
- Plugins e a interface de gerenciamento. Plugins compilados para a 3.x precisam de builds para a 4.x. O próprio plugin de gerenciamento continua, mas perde as telas de espelhamento, e o plugin de AMQP 1.0 deixa de ter efeito. Audite qualquer plugin da comunidade antes de presumir que ele funciona.
- MQTT 5. O suporte a MQTT 5 chegou na 3.13 e continua na 4.x. Se você vem da 3.12 ou de uma versão anterior, seus clientes MQTT ganham esse suporte ao longo do caminho.
- Erlang. A 4.x exige Erlang/OTP 26 ou posterior. Se os seus nós ainda estão no OTP 25, o upgrade do Erlang acontece como parte do rolling upgrade, um nó por vez. Veja nossa nota sobre o fim de vida do Erlang 26 e o RabbitMQ antes de escolher a versão de destino.
Devemos continuar na 3.13 ou fazer o upgrade para a 4.x?
A 3.13 é a última série 3.x. A janela de suporte da comunidade para ela é curta e, quando ela se fecha, não há mais patches de segurança upstream para nenhuma versão 3.x. Essa é a restrição real que orienta a decisão.
Continuar na 3.13 é razoável em exatamente um caso: você tem um contrato de suporte comercial ou estendido que faz o backport de correções de segurança para a versão que você roda. Sem isso, um cluster 3.13 é uma contagem regressiva de CVEs. Nosso suporte LTS estendido cobre da 3.8.x à 3.13.x com patches com backport, e é isso que permite aos clientes rodar séries mais antigas em um cronograma que eles controlam, e não em um ditado pelo calendário upstream. Isso ganha tempo; não elimina a necessidade de planejar a migração.
Faça o upgrade quando estas quatro condições forem verdadeiras:
- Não há mais filas clássicas espelhadas nem políticas de HA.
- Todas as feature flags estáveis estão habilitadas em todos os nós.
- O Erlang está no OTP 26 ou posterior, ou você está pronto para atualizá-lo durante o rolling upgrade.
- As aplicações cliente estão em versões de bibliotecas mantidas que se comportam corretamente com filas de quórum (tratamento correto de
x-delivery-limit, dead lettering e reconexão).
Faça o upgrade antes do que o seu calendário de manutenção sugere se você precisa de AMQP 1.0 sem o plugin, de MQTT 5 em uma 3.x mais antiga ou das melhorias das filas de quórum da 4.x, que incluem prioridades de mensagens e um delivery limit padrão que impede que mensagens envenenadas circulem para sempre.
Se você 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 vá para a 4.x. Executamos as duas metades para clientes, e o serviço de upgrades e patches de RabbitMQ tem o escopo definido dessa forma.
Se continuar é seguro é uma questão separada de se é possível: o RabbitMQ 3.x ainda é seguro? analisa, série por série, as datas de fim de vida e a exposição a CVEs. Se você continuar, o suporte LTS estendido para RabbitMQ 3.x mantém a versão com patches enquanto o upgrade espera uma janela.
O runbook de rolling upgrade que usamos
Esta é a sequência que seguimos nos clusters dos clientes. Ela pressupõe um cluster de três ou cinco nós, filas de quórum para tudo o que importa e clientes que se reconectam ao perder a conexão.
- Inventário. Registre as versões, as versões do Erlang, os plugins habilitados e todas as políticas. Rode
rabbitmq-diagnostics check_if_any_deprecated_features_are_usederabbitmq-diagnostics check_if_cluster_has_classic_queue_mirroring_policyem qualquer nó. Os dois precisam voltar sem problemas antes de continuar. - Habilite todas as feature flags estáveis.
rabbitmqctl enable_feature_flag allem um nó vale para todo o cluster. Confirme comrabbitmqctl list_feature_flags; qualquer flag aindadisabledbloqueia o upgrade. - Converta as filas clássicas espelhadas em filas de quórum, fluxo por 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, drene a fila antiga e exclua-a. Faça isso por 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 do OTP 26 ou posterior está disponível em todos os nós e que é a versão com a qual o seu build 4.x foi testado.
- Exporte as definições e faça um backup.
rabbitmqctl export_definitionsmais um backup do sistema de arquivos do diretório de dados em todos os nós. A exportação das definições é a base para reconstruir o cluster se o limite de rollback for ultrapassado. - Atualize um nó por vez. Antes de parar um nó, rode
rabbitmq-upgrade await_online_quorum_plus_onepara que nenhuma fila de quórum perca a maioria enquanto esse nó estiver fora. Depois,rabbitmq-upgrade draincoloca o nó em modo de manutenção, fecha as conexões dos clientes de forma ordenada e transfere a liderança das filas de quórum para outros nós. Pare o serviço, atualize o Erlang se necessário, atualize o RabbitMQ, inicie o serviço e confirme que o nó voltou ao cluster. - Espere os membros das filas de quórum se atualizarem.
rabbitmq-queues quorum_status <queue>nas filas mais movimentadas, ourabbitmq-diagnostics check_if_node_is_quorum_criticalno próximo nó que você pretende parar. Não comece o próximo nó até que isso passe. - Verifique se os clientes se reconectaram. A contagem de conexões na interface de gerenciamento deve voltar ao nível normal no nó atualizado. Se uma biblioteca cliente não se reconectar, corrija agora, antes do próximo nó.
- Repita para cada nó restante. O cluster roda com 3.13 e 4.x misturados durante essa janela. Não altere políticas, não adicione filas e não habilite nada novo até terminar o último nó.
- Habilite as novas feature flags da 4.x. Depois de atualizar o último nó, rode
rabbitmqctl enable_feature_flag allnovamente. Esse é o limite de rollback: depois que uma feature flag exclusiva da 4.x é habilitada, não há caminho de downgrade. Tudo antes dessa etapa 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 é pequeno o bastante para ser reconstruído, a exportação das definições é confiável e você pode mover os clientes por DNS ou load balancer. Ele entrega um cluster 4.x limpo e um cluster 3.13 intacto para onde voltar. Preferimos essa opção para clusters que acumularam anos de políticas não documentadas.
De qualquer forma, o suporte cobre a janela de upgrade com resposta de 15 minutos para P1, o que importa principalmente entre a etapa 6 e a etapa 10.
Perguntas frequentes
Posso fazer o upgrade direto do RabbitMQ 3.13 para o 4.x?
Sim. Um rolling upgrade da 3.13.x para a 4.0.x é suportado, desde que todas as feature flags estáveis estejam habilitadas, não reste nenhuma política de espelhamento de filas clássicas e o Erlang esteja no OTP 26 ou posterior. Se você está na 3.12 ou em uma versão anterior, não dá para pular direto para a 4.x; faça primeiro o upgrade para a 3.13, habilite as feature flags dela e depois continue. O motivo é que nós 4.x só entram em clusters em que o conjunto de feature flags da 3.13 está totalmente habilitado, e séries mais antigas não conseguem atender a isso.
Posso continuar no RabbitMQ 3.x?
Pode, mas só com segurança se tiver um contrato de suporte que faça o backport de correções de segurança, porque os patches upstream da 3.x terminam com a janela da comunidade da 3.13. Nosso suporte LTS estendido cobre da 3.8.x à 3.13.x com patches de CVEs com backport exatamente para essa situação. Continuar faz sentido quando uma migração de clientes, um congelamento por 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; planeje a migração para a 4.x no seu próprio cronograma.
Como fazer o upgrade do RabbitMQ sem downtime?
Com um rolling upgrade, um nó por vez. Habilite todas as feature flags, remova as filas clássicas espelhadas, exporte as definições e, para cada nó, rode rabbitmq-upgrade await_online_quorum_plus_one, faça o drain, atualize o Erlang e o RabbitMQ, reinicie e espere os membros das filas de quórum se atualizarem antes de mexer no próximo nó. Clientes que se reconectam ao perder a conexão veem uma breve reconexão, e não uma indisponibilidade. O blue-green, com um novo cluster 4.x e um cutover dos clientes, é a opção quando o cluster atual está emaranhado demais para um upgrade in-place.
O RabbitMQ 4 exige Erlang 26?
Sim. O RabbitMQ 4.x exige Erlang/OTP 26 ou posterior. Se os seus nós 3.13 já estão no OTP 26, a etapa do Erlang não exige nada; se estão no OTP 25, atualize o Erlang em cada nó durante a mesma janela de rolling upgrade do pacote do RabbitMQ. Consulte a tabela de compatibilidade para o patch exato da 4.x que você vai instalar, já que versões 4.x posteriores elevam o mínimo. Nosso post sobre o fim de vida do Erlang 26 explica o que isso significa para os prazos de suporte.