RabbitMQ

RabbitMQ no Kubernetes e no OpenShift: um playbook de implantação

Scott Sternloff

Por Scott Sternloff, Arquiteto corporativo sênior

LinkedIn · Atualizado em

K8sStatefulSet · 3 ReplicasKubernetes & OpenShift
Nesta página
Rodar o RabbitMQ no Kubernetes ou no OpenShift é cada vez mais comum e, cada vez mais, a origem de surpresas operacionais para equipes que imaginam que o Kubernetes vai simplesmente absorver a complexidade. Não vai — pelo menos não sem entender como os mecanismos de quórum do RabbitMQ interagem com o gerenciamento do ciclo de vida dos pods no Kubernetes.
Este guia cobre os principais padrões de implantação, as armadilhas específicas que causam incidentes em produção e como estruturar a sua implantação de RabbitMQ no Kubernetes para uma operação confiável.

Como implantar o RabbitMQ no Kubernetes?

A abordagem padrão é o RabbitMQ Cluster Operator, o operator oficial para Kubernetes mantido pela Broadcom. O operator cuida de:
  • Implantar o RabbitMQ como StatefulSet, com nomes de pod corretos e identidades de rede estáveis
  • Gerenciar os PersistentVolumeClaims (PVCs) do armazenamento de dados de cada nó do cluster
  • Lidar com a participação no cluster, a descoberta de nós e o Erlang cookie
  • Oferecer um custom resource RabbitmqCluster para a configuração declarativa do cluster
No OpenShift, o mesmo operator funciona com alguma configuração adicional de SCC (Security Context Constraint). A AceMQ também dá suporte a implantações em RKE2, AKS, ACK e outras variantes de Kubernetes gerenciado.
Configuração mínima do cluster: três nós, cada um em um worker node diferente do Kubernetes (garantido por regras de pod anti-affinity). Rodar dois pods do RabbitMQ no mesmo worker node anula a alta disponibilidade.

O que é o termination grace period e por que ele importa?

O RabbitMQ Cluster Operator inclui um hook pre-stop com termination grace period padrão de 604.800 segundos (uma semana). Isso não é um erro — é um mecanismo de segurança.
Antes de um pod do RabbitMQ ser desligado, o hook pre-stop verifica se alguma fila cujo líder está naquele pod se encontra em estado crítico de quórum — ou seja, se o desligamento do pod deixaria uma ou mais filas abaixo do quórum. Se for o caso, o pod se recusa a encerrar até que o quórum seja restabelecido.

“O que o hook pre-stop faz é verificar se nenhuma das filas está em estado crítico de quórum antes de permitir que o pod saia. Ele está protegendo o quórum. Mas quando você vai de três para zero réplicas, isso cria um deadlock — porque derrubar um pod deixa o quórum crítico, o que impede esse pod de encerrar, o que impede o cluster de ser desligado.”

— Scott Sternloff, Principal Architect da AceMQ, sessão do projeto com a Adeptia, abril de 2026

Como escalar um cluster RabbitMQ para zero no Kubernetes com segurança?

O procedimento seguro para reduzir a zero exige dois passos executados em sequência, e não ao mesmo tempo:
Passo 1: reduza o termination grace period para 30 segundos:
kubectl patch rabbitmqcluster <cluster-name> -n <namespace> \
  --type merge \
  -p '{"spec": {"terminationGracePeriodSeconds": 30}}'
Passo 2: depois que essa alteração entrar em vigor, escale as réplicas para zero:
kubectl patch rabbitmqcluster <cluster-name> -n <namespace> \
  --type merge \
  -p '{"spec": {"replicas": 0}}'
Quando religar o cluster, restaure o grace period para o valor padrão:
kubectl patch rabbitmqcluster <cluster-name> -n <namespace> \
  --type merge \
  -p '{"spec": {"replicas": 3, "terminationGracePeriodSeconds": 604800}}'

O que acontece quando um nó do Kubernetes passa por drain durante um upgrade do cluster?

Quando um upgrade do cluster Kubernetes faz o drain de um nó, os pods desse nó são encerrados. Se um pod do RabbitMQ estiver rodando nesse nó e suas filas estiverem em estado crítico de quórum, o pod ficará preso no estado terminating — bloqueando o drain do nó, bloqueando o upgrade e exigindo intervenção manual.

“Os seus clientes têm um processo automatizado para fazer o upgrade do cluster. Um nó pode cair por vez. E como o pod do RabbitMQ que roda nesse nó se recusa a encerrar por causa da proteção de quórum, ele não deixa o nó passar pelo drain. O processo de upgrade fica travado.”

— Scott Sternloff, Principal Architect da AceMQ, sessão com a Adeptia, abril de 2026

Soluções:
  1. Reduza o termination grace period padrão antes das janelas de upgrade automatizado e restaure-o depois
  2. Configure um watchdog: se um pod não encerrar em N segundos após receber um SIGTERM, force a exclusão (use com cautela)
  3. Use pod disruption budgets (PDBs): um PDB que permita no máximo um pod indisponível por vez garante que o Kubernetes respeite as restrições de quórum durante os drains de nós

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

Fale conosco

O que você nunca deve fazer com pods do RabbitMQ no Kubernetes?

Nunca force a exclusão de um pod do RabbitMQ sem entender o impacto no quórum. A exclusão forçada (kubectl delete pod --force --grace-period=0) ignora completamente o hook pre-stop. Se o pod excluído à força for o líder de quórum de alguma fila, essas filas perdem o quórum na hora.
Nunca rode dois pods do RabbitMQ no mesmo nó do Kubernetes. As regras de anti-affinity devem impedir isso automaticamente, mas confirme que a sua configuração de anti-affinity está correta.
Nunca reduza de 3 réplicas para um número menor sem antes verificar a saúde do quórum.
kubectl exec -n <namespace> <rabbitmq-pod> -- rabbitmq-diagnostics check_running
kubectl exec -n <namespace> <rabbitmq-pod> -- rabbitmq-queues check_if_node_is_quorum_critical
Se alguma fila aparecer como crítica de quórum, espere que ela se recupere antes de prosseguir com a redução.

Considerações sobre storage e monitoramento

Cada pod do RabbitMQ precisa de um PersistentVolumeClaim. Para produção:
  • Use uma StorageClass com volumeBindingMode: WaitForFirstConsumer para garantir que os pods e seus volumes fiquem na mesma zona de disponibilidade
  • Storage SSD ou NVMe é fortemente recomendado — as escritas no WAL das filas de quórum são sensíveis à latência
  • Defina a política de retenção dos PVCs como Retain para que os dados sobrevivam à exclusão do pod
  • Não use storage compartilhado (NFS, sistemas de arquivos compartilhados) para os volumes de dados do RabbitMQ
Principais métricas a acompanhar em implantações específicas de Kubernetes:
  • rabbitmq_quorum_queue_stat_voters — confirma que o quórum se mantém entre os nós
  • Contagem de reinícios de pods — reinícios frequentes indicam problemas de quórum ou de recursos
  • Capacidade dos PVCs — monitore a utilização de disco do PVC de cada pod
  • rabbitmq_node_disk_free — alerte antes que o alarme de disco dispare
Se você está planejando uma nova implantação, migrando um cluster existente para o Kubernetes ou enfrentando problemas ligados a upgrades, fale com o suporte da AceMQ para arquitetura de implantação ou suporte hands-on.

As imagens base são uma questão recorrente de cadeia de suprimentos nessas implantações — veja segurança das imagens Bitnami e as alternativas corporativas.

RabbitMQ no Kubernetes ou em máquinas virtuais: como decidir

O RabbitMQ roda bem nos dois. Os fatores decisivos são quem opera a plataforma e como é o storage por baixo dela.

  • Quem opera. Se uma equipe de plataforma já roda cargas stateful no Kubernetes, com operator, PodDisruptionBudgets e upgrades de StatefulSet como rotina diária, o RabbitMQ é só mais um StatefulSet. Se a sua equipe de infraestrutura opera bem as VMs e o Kubernetes é apenas onde ficam as aplicações stateless, colocar o broker lá significa que a equipe de mensageria vai aprender os modos de falha do Kubernetes em um sistema de produção.
  • Storage. As filas de quórum e os streams fazem fsync a cada lote de escritas. Em uma VM com NVMe local, isso leva menos de um milissegundo. No Kubernetes, o padrão é um PersistentVolume conectado via rede, e cada fsync atravessa a rede de storage. Costumamos ver de 2 a 5 ms por fsync em block storage na nuvem, o que aparece diretamente como latência de publisher confirms nas filas de quórum. Existem provisionadores de PV local, mas eles prendem o pod a um nó. Filas clássicas vs. filas de quórum explica por que as filas de quórum são mais sensíveis a isso do que as clássicas.
  • Upgrades. O Kubernetes faz um rolling restart do StatefulSet, um pod por vez, com o operator esperando o quórum antes de cada passo. Em VMs, você faz o upgrade no lugar, nó a nó, no seu próprio cronograma. A versão Kubernetes é mais automatizada e menos tolerante a uma premissa errada.
  • Domínios de falha. No Kubernetes, nós passam por drain, pods são despejados e o autoscaler recupera capacidade sem pedir licença. Um PDB e o pod anti-affinity são a única coisa entre um drain de rotina e um quórum perdido. VMs falham com menos frequência e em janelas que você controla, mas falham de forma mais dura, sem um scheduler para reiniciar o broker em outro lugar.
  • Rede. Os pods recebem hostnames do headless service e IPs que mudam a cada reinício. Os clientes se conectam por um Service ou ingress e precisam se reconectar de forma limpa, porque eles vão ser reconectados. Qualquer coisa que fixe o IP de um broker quebra. Em VMs, os hostnames ficam estáveis por anos e os bugs de reconexão dos clientes continuam escondidos.
  • Licenciamento. O Tanzu RabbitMQ, a distribuição comercial, é empacotado primeiro para Kubernetes, com uma imagem de VM ao lado. O RabbitMQ open source roda em qualquer lugar.

Nossa recomendação: VMs quando a equipe é pequena e predominam cargas de filas de quórum sensíveis à latência. Kubernetes quando existe uma equipe de plataforma, um operator em uso e o resto do ambiente já está lá. Nos nossos projetos, a divisão é mais ou menos equilibrada, e as implantações em Kubernetes que dão errado são quase sempre aquelas adotadas porque o Kubernetes estava disponível, e não porque alguém estava preparado para operar cargas stateful nele.

Operator, chart Helm ou StatefulSet feito à mão

O RabbitMQ Cluster Kubernetes Operator é a opção mantida upstream e a que adotamos por padrão. Você declara um recurso RabbitmqCluster e o operator cria o StatefulSet, o headless service para a descoberta de pares, o Service dos clientes, os Secrets do Erlang cookie e do usuário padrão e a configuração do servidor. Ele faz rolling restarts com um hook preStop que espera quórum mais um antes de derrubar um nó, e configura o TLS a partir de um Secret que você indicar. Ele não cria um PodDisruptionBudget sozinho; adicione um com maxUnavailable: 1. Ao lado dele, o Messaging Topology Operator transforma usuários, vhosts, permissões, filas, exchanges, bindings, policies, shovels e upstreams de federation em CRDs, para que a topologia fique no Git junto com a definição do cluster.

Um cluster mínimo com cara de produção:

apiVersion: rabbitmq.com/v1beta1
kind: RabbitmqCluster
metadata:
  name: orders
spec:
  replicas: 3
  resources:
    requests:
      cpu: "2"
      memory: 8Gi
    limits:
      cpu: "2"
      memory: 8Gi
  persistence:
    storageClassName: fast-ssd
    storage: 100Gi
  rabbitmq:
    additionalConfig: |
      cluster_partition_handling = pause_minority
      vm_memory_high_watermark.relative = 0.6
      disk_free_limit.absolute = 5GB

No RabbitMQ 4.3 e posteriores, remova a linha cluster_partition_handling: a versão 4.3.0 eliminou as estratégias de tratamento de partição e a chave não tem mais efeito. Mantenha os requests iguais aos limits. O operator deriva o override de memória do RabbitMQ a partir da configuração de memória do pod, de modo que o high watermark e o limite do cgroup fiquem alinhados. Adicione spec.affinity com pod anti-affinity entre nós, ou entre zonas, se você as tiver.

  • Os charts Helm da comunidade geram, a partir de templates, um StatefulSet mais os services, a configuração e os secrets em um único helm install. Eles servem para colocar um cluster de pé. Depois da instalação, não fazem nada: nenhum rolling upgrade ordenado que espere o quórum, nenhum gerenciamento de topologia, e cada helm upgrade reescreve o StatefulSet e torce para dar certo. Se você padroniza tudo em Helm, rode o operator e gerencie o recurso RabbitmqCluster com um chart.
  • Um StatefulSet feito à mão se justifica em dois casos: um cluster em que você não pode instalar CRDs nem operators com escopo de cluster, ou uma equipe que já tem um padrão de StatefulSet endurecido para outros sistemas stateful e quer que o RabbitMQ siga o mesmo modelo. O que você assume é tudo o que foi descrito acima: configuração da descoberta de pares, o hook preStop de drain, o ajuste das probes, a rotação de secrets e a coreografia de upgrade. O bug recorrente que herdamos é um upgrade que reiniciou dois pods de uma vez.

Os modos de falha no Kubernetes pelos quais somos chamados

  • Um drain levou o líder do quórum, e o PDB deixou. Sintoma: os publishers ficam bloqueados esperando confirms por 10 a 30 segundos durante um upgrade de nó de rotina, ou uma fila informa que não tem líder porque duas de três réplicas estão fora do ar. Causa: nenhum PDB, ou um que permite mais de um pod indisponível, combinado com um upgrade de cluster que faz drain dos nós mais rápido do que as filas de quórum conseguem reeleger e se atualizar. Correção: um PDB com maxUnavailable: 1, pod anti-affinity para que as réplicas nunca compartilhem um nó e o hook preStop do operator (ou o seu próprio rabbitmq-upgrade await_online_quorum_plus_one) para que o drain espere.
  • Reconexão do PV após a falha de um nó. Sintoma: depois que um nó cai, o pod do RabbitMQ dele fica em ContainerCreating com um erro Multi-Attach ou um conflito de node affinity do volume por seis minutos ou mais. Causa: o block storage vinculado a uma zona só pode ser conectado na própria zona, e a conexão do nó morto só é liberada quando o node controller desiste dele. Correção: o cluster continua de pé com duas de três réplicas se o anti-affinity as tiver distribuído, então não brigue com isso. Use uma storage class WaitForFirstConsumer para que o volume fique na zona do pod e trate a janela de reconexão como um custo conhecido do storage em rede.
  • OOM kill antes do flow control. Sintoma: um pod reinicia com exit code 137 e nenhum erro do RabbitMQ no log; o alarme de memória nunca disparou. Causa: o limite de memória do contêiner fica abaixo do ponto em que o high watermark entraria em ação, seja porque o RabbitMQ leu a memória do host em vez do limite do cgroup, seja porque o watermark não deixa folga para os alocadores e o binary heap da VM Erlang. Correção: requests iguais aos limits, um watermark que fique de 20 a 30 por cento abaixo do limite e rabbitmq-diagnostics memory_breakdown para confirmar que o total enxergado pelo RabbitMQ corresponde ao do pod.
  • Reinícios pela liveness probe durante a recuperação. Sintoma: após um reinício não limpo, um nó com filas grandes entra em CrashLoopBackOff, e cada tentativa avança um pouco mais na reconstrução dos índices antes que o kubelet a mate. Causa: uma liveness probe que roda rabbitmq-diagnostics check_running ou algo parecido falha enquanto o nó reproduz o Mnesia ou o Khepri e reconstrói os índices das filas, o que, em um nó grande, leva mais tempo do que o limite de falhas da probe. Correção: uma startup probe com failureThreshold generoso, uma readiness probe apenas na porta 5672 e nenhuma liveness probe agressiva. O operator vem sem liveness probe exatamente por esse motivo.
  • Uma mudança de DNS ou do headless service quebrou a descoberta de pares. Sintoma: os pods sobem, mas cada um forma um cluster de um só nó, ou se recusam a inicializar porque o diretório de dados pertence a um nó com outro nome. Causa: os nomes dos nós derivam do hostname do pod e do headless service, então renomear o service, o namespace ou o domínio DNS do cluster muda o nome de todos os nós e deixa órfãos os dados em disco. Correção: não renomeie. Se a renomeação for inevitável, trate-a como uma migração para um cluster novo: exporte as definições, use shovel ou esvazie as filas e migre os clientes.

Para a lista mais ampla do que quebra quando a mensageria vai para o Kubernetes, veja o que quebra na mensageria no Kubernetes. Para saber o que monitorar para que esses problemas cheguem como alertas, e não como chamados, veja monitoramento do RabbitMQ no Kubernetes. Se você prefere contar com quem já corrigiu esses problemas antes, conheça nossa consultoria em Kubernetes e contêineres e o nosso suporte RabbitMQ.

A sequência completa — se o Kubernetes é o lugar certo, o Operator, storage classes, network policy, requests e limits, monitoramento e rolling updates — está no guia do RabbitMQ no Kubernetes.

Perguntas frequentes

É melhor rodar o RabbitMQ no Kubernetes ou em máquinas virtuais?

As duas opções funcionam. Rode em VMs quando a equipe é pequena, a carga depende de filas de quórum (quorum queues) ou streams com latência apertada de publisher confirms e você ainda não opera cargas stateful no Kubernetes. Rode no Kubernetes quando existe uma equipe de plataforma, você usa o Cluster Operator e as aplicações que conversam com o broker já estão lá. O storage é a questão que mais pesa: volumes conectados via rede acrescentam milissegundos a cada fsync, e as filas de quórum fazem fsync o tempo todo. Operamos os dois modelos para clientes. Nenhum deles é errado por si só; errado é escolher o Kubernetes sem ninguém preparado para operá-lo.

Qual operator do RabbitMQ para Kubernetes devemos usar?

O RabbitMQ Cluster Kubernetes Operator, mantido upstream pela equipe do RabbitMQ, em conjunto com o Messaging Topology Operator. O Cluster Operator gerencia o recurso RabbitmqCluster: StatefulSet, services, secrets, configuração, TLS e rolling restarts que respeitam o quórum. O Topology Operator gerencia usuários, vhosts, filas, exchanges, bindings e policies como recursos do Kubernetes, para que a topologia fique versionada no Git. Adicione o seu próprio PodDisruptionBudget. Os charts Helm servem para uma primeira instalação, mas não gerenciam nada depois dela. Um StatefulSet feito à mão só faz sentido onde CRDs não são permitidos.

O RabbitMQ roda bem no OpenShift?

Sim. Operamos RabbitMQ no OpenShift para clientes corporativos, ao lado de EKS, AKS e GKE. O Cluster Operator é instalado pelo OperatorHub, e seus pods rodam sob a SCC restricted desde que o security context do pod fique a cargo do OpenShift, e não do operator, algo que o spec.override permite. O que muda em relação ao Kubernetes puro são as Routes no lugar do Ingress para AMQP sobre TLS, as permissões de volume determinadas pela SCC e a cadência própria de upgrade de nós do OpenShift, que torna obrigatórias, e não apenas desejáveis, as recomendações de PDB e anti-affinity acima.

Quantas réplicas do RabbitMQ um cluster Kubernetes deve ter?

Três, distribuídas entre nós e, idealmente, entre zonas com pod anti-affinity. Três réplicas toleram uma perda enquanto as filas de quórum mantêm a maioria, e uma perda é exatamente o que um drain, uma falha de nó ou uma etapa de upgrade provoca. Cinco só compensam quando você precisa sobreviver à queda de uma zona e a um evento de manutenção ao mesmo tempo. Nunca duas: as filas de quórum precisam de maioria, e dois nós a perdem em qualquer falha isolada. Escalar throughput é uma questão separada da quantidade de réplicas, e HA, DR e dimensionamento de cluster trata do dimensionamento.

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