RabbitMQ

Upgrade do RabbitMQ 3.x para 4.x sem downtime: rolling vs. blue-green

Scott Sternloff

Por Scott Sternloff, Arquiteto corporativo sênior

LinkedIn · Atualizado em

3.13EOL4.xCURRENTNo DowntimeRolling & Blue-Green Upgrade
Nesta página
O upgrade do RabbitMQ é uma daquelas operações que deveriam ser simples, mas que rotineiramente pegam as equipes de surpresa. As restrições do caminho de versões não são óbvias, a dependência do Erlang acrescenta mais uma peça móvel, e o custo de errar em produção é alto.
Este post trata das duas estratégias que funcionam — rolling upgrade e implantação blue-green — e das etapas pré-upgrade que a maioria das equipes esquece, incluindo a habilitação das feature flags e as verificações de compatibilidade de versão do Erlang.

Por que os upgrades do RabbitMQ dão errado?

O padrão de falha mais comum é uma equipe que não faz upgrade há um ano ou mais, decide saltar para a versão mais recente e pula as etapas intermediárias que o caminho de upgrade exige.

"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

O RabbitMQ tem um caminho de upgrade definido. Não dá para pular versões major. Se você está na 3.12, precisa fazer o upgrade para a 3.13 antes de poder ir para a 4.x. Tentar saltar direto causa instabilidade no cluster e problemas de compatibilidade difíceis de diagnosticar.

Qual é o caminho de upgrade obrigatório da 3.x para a 4.x?

O caminho de upgrade de versões é documentado pela Broadcom e precisa ser seguido à risca. A regra principal: só é possível avançar uma versão major por vez.
Da 3.12 → é preciso ir para a 3.13 → e depois para a 4.x. Não dá para ir da 3.12 direto para a 4.1. Se você está mais atrasado — na 3.10 ou na 3.11 —, precisa passar por cada versão major em sequência.
Antes de cada etapa de upgrade, também é preciso habilitar todas as feature flags da versão atual antes de prosseguir:
rabbitmqctl enable_feature_flag all
Pular a habilitação das feature flags antes de um salto de versão é uma causa comum de falhas de upgrade. Sempre confirme que todas as flags aparecem como habilitadas antes de passar para a próxima versão.

E a compatibilidade com o Erlang?

Cada versão do RabbitMQ especifica uma versão mínima e uma máxima do Erlang suportadas. Atualizar o RabbitMQ sem antes atualizar o Erlang para a versão exigida faz a nova versão do RabbitMQ falhar.
Pontos de verificação do Erlang no caminho 3.12 → 3.13 → 4.x:
  • 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)

Um rolling upgrade atualiza os nós do cluster existente um por vez, sem criar um novo cluster. Você para um nó, atualiza o RabbitMQ (e o Erlang, se necessário), reinicia e passa para o próximo nó.
Como funciona:
  1. Pare o nó 1 (apenas o serviço — não o sistema operacional)
  2. Atualize o Erlang no nó 1 para a versão exigida
  3. Atualize o RabbitMQ no nó 1 para a versão de destino
  4. Inicie o serviço do RabbitMQ no nó 1
  5. Confirme que o nó 1 voltou ao cluster e está saudável
  6. Repita para os nós 2 e 3
Durante o rolling upgrade, o cluster roda temporariamente com versões mistas. Isso é suportado dentro de uma mesma versão major, mas não entre versões major diferentes. Faça rolling upgrades em períodos de pouco tráfego — atualizar sob carga pesada aumenta o risco, porque a replicação de quórum e a sincronização de mensagens geram overhead adicional.
Prós: não exige nova infraestrutura, orquestração mais simples, usa a composição atual do cluster. Contras: os breves reinícios de cada nó interrompem conexões; precisa ser feito em horários de pouco tráfego.

Estratégia 2: implantação blue-green

Uma implantação blue-green cria um cluster totalmente novo (green) ao lado do cluster existente (blue), migra o tráfego para o novo cluster usando federation e desativa o antigo quando a transição termina.
Como funciona:
  1. Provisione um novo cluster (green) na versão de destino do RabbitMQ e do Erlang
  2. Configure um upstream de fila federada no cluster green apontando para o cluster blue
  3. À medida que os consumers são movidos para o cluster green, a federation puxa automaticamente as mensagens do blue para o green
  4. Quando todos os consumers estiverem no green, mova os producers para o green
  5. Depois de mover os producers, drene as mensagens restantes do blue usando o plugin shovel
  6. Desative o cluster blue
Diferença fundamental: use filas federadas, e não exchanges federadas. Com filas federadas, quando há um consumer no cluster downstream (green), as mensagens são puxadas do cluster upstream (blue) e consumidas lá — elas não ficam persistidas nos dois lados.

"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

Prós: migração com zero downtime, pode ser feita a qualquer momento. Contras: exige infraestrutura duplicada temporariamente e mais etapas de configuração.

Metas de resposta a partir de 15 minutos, conforme o plano. Engenheiros sêniores designados.

Fale conosco

Checklist pré-upgrade

Antes de iniciar qualquer upgrade do RabbitMQ:
  • 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
Upgrades do RabbitMQ que atravessam várias versões — especialmente o salto da 3.x para a 4.x — estão entre os tipos de projeto mais comuns que atendemos. Se você quiser ajuda para definir o escopo do upgrade, desenhar a abordagem de migração ou ter um engenheiro da AceMQ executando o upgrade na sua janela de manutenção, fale com a nossa equipe de suporte RabbitMQ.

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-mode e ha-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_policy informa 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-type ainda gera uma fila clássica, a menos que o virtual host defina default_queue_type. Defina-o como quorum por vhost para novas cargas de trabalho e garanta que o código cliente que declara filas passe um x-queue-type explí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:

  1. Não há mais filas clássicas espelhadas nem políticas de HA.
  2. Todas as feature flags estáveis estão habilitadas em todos os nós.
  3. O Erlang está no OTP 26 ou posterior, ou você está pronto para atualizá-lo durante o rolling upgrade.
  4. 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.

  1. 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_used e rabbitmq-diagnostics check_if_cluster_has_classic_queue_mirroring_policy em qualquer nó. Os dois precisam voltar sem problemas antes de continuar.
  2. Habilite todas as feature flags estáveis. rabbitmqctl enable_feature_flag all em um nó vale para todo o cluster. Confirme com rabbitmqctl list_feature_flags; qualquer flag ainda disabled bloqueia o upgrade.
  3. 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.
  4. 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.
  5. Exporte as definições e faça um backup. rabbitmqctl export_definitions mais 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.
  6. Atualize um nó por vez. Antes de parar um nó, rode rabbitmq-upgrade await_online_quorum_plus_one para que nenhuma fila de quórum perca a maioria enquanto esse nó estiver fora. Depois, rabbitmq-upgrade drain coloca 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.
  7. Espere os membros das filas de quórum se atualizarem. rabbitmq-queues quorum_status <queue> nas filas mais movimentadas, ou rabbitmq-diagnostics check_if_node_is_quorum_critical no próximo nó que você pretende parar. Não comece o próximo nó até que isso passe.
  8. 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ó.
  9. 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ó.
  10. Habilite as novas feature flags da 4.x. Depois de atualizar o último nó, rode rabbitmqctl enable_feature_flag all novamente. 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 drain

O 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.

Consulta gratuita

Um olhar especializado sobre seu cluster RabbitMQ

Seja para resolver um incidente em produção, planejar uma migração ou ter uma segunda opinião sobre sua arquitetura, nossa equipe está pronta. Sem discurso de vendas, só respostas.

Envie um e-mail