RabbitMQ

RabbitMQ em Kubernetes e OpenShift: um guia prático de implementação

Scott Sternloff

Por Scott Sternloff, Arquiteto empresarial sénior

LinkedIn · Atualizado a

K8sStatefulSet · 3 ReplicasKubernetes & OpenShift
Nesta página
Executar RabbitMQ em Kubernetes ou OpenShift é cada vez mais comum, e cada vez mais a origem de surpresas operacionais para as equipas que partem do princípio de que o Kubernetes vai simplesmente tratar da complexidade. Não trata — pelo menos não sem perceber como os mecanismos de quórum do RabbitMQ interagem com a gestão do ciclo de vida dos pods no Kubernetes.
Este guia cobre os principais padrões de implementação, as armadilhas concretas que causam incidentes em produção e a forma de estruturar a sua implementação de RabbitMQ em Kubernetes para uma operação fiável.

Como implementar RabbitMQ em Kubernetes?

A abordagem padrão é o RabbitMQ Cluster Operator, o operador Kubernetes oficial mantido pela Broadcom. O operador trata de:
  • Implementar o RabbitMQ como StatefulSet, com nomes de pods corretos e identidades de rede estáveis
  • Gerir os PersistentVolumeClaims (PVCs) para o armazenamento de dados de cada nó do cluster
  • Tratar da pertença ao cluster, da descoberta de nós e do cookie Erlang
  • Disponibilizar um recurso personalizado RabbitmqCluster para a configuração declarativa do cluster
No OpenShift, o mesmo operador funciona com alguma configuração adicional de SCC (Security Context Constraint). A AceMQ também dá suporte a implementações em RKE2, AKS, ACK e outras variantes geridas de Kubernetes.
Configuração mínima do cluster: três nós, cada um num worker node Kubernetes diferente (imposto através de regras de anti-afinidade de pods). Executar dois pods de RabbitMQ no mesmo worker node anula a alta disponibilidade.

O que é o período de tolerância de encerramento e porque é importante?

O RabbitMQ Cluster Operator inclui um hook pre-stop com um período de tolerância de encerramento predefinido de 604.800 segundos (uma semana). Não é um erro — é um mecanismo de segurança.
Antes de um pod de RabbitMQ ser encerrado, o hook pre-stop verifica se alguma das filas cujo líder está atualmente nesse pod se encontra num estado crítico de quórum — ou seja, se o encerramento do pod faria uma ou mais filas ficar abaixo do quórum. Se essa condição se verificar, o pod recusa-se a terminar até o quórum ser restabelecido.

«O que o hook pre-stop faz é verificar se nenhuma das filas está num estado crítico de quórum antes de permitir que o pod saia. Está a proteger o quórum. Mas quando se passa de três para zero réplicas, cria-se um deadlock — porque desligar um pod torna o quórum crítico, o que impede esse pod de terminar, o que impede o cluster de ser desligado.»

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

Como reduzir com segurança um cluster RabbitMQ a zero em Kubernetes?

O procedimento seguro para reduzir a zero exige dois passos executados em sequência, e não em simultâneo:
Passo 1: reduzir o período de tolerância de encerramento para 30 segundos:
kubectl patch rabbitmqcluster <cluster-name> -n <namespace> \
  --type merge \
  -p '{"spec": {"terminationGracePeriodSeconds": 30}}'
Passo 2: depois de essa alteração entrar em vigor, reduzir as réplicas a zero:
kubectl patch rabbitmqcluster <cluster-name> -n <namespace> \
  --type merge \
  -p '{"spec": {"replicas": 0}}'
Quando voltar a levantar o cluster, reponha o período de tolerância no valor predefinido:
kubectl patch rabbitmqcluster <cluster-name> -n <namespace> \
  --type merge \
  -p '{"spec": {"replicas": 3, "terminationGracePeriodSeconds": 604800}}'

O que acontece quando é feito o drain de um nó Kubernetes durante uma atualização do cluster?

Quando uma atualização de um cluster Kubernetes faz o drain de um nó, os pods desse nó são terminados. Se um pod de RabbitMQ estiver a correr no nó em drain e as suas filas estiverem em estado crítico de quórum, o pod fica preso no estado terminating — bloqueando o drain do nó, bloqueando a atualização e exigindo intervenção manual.

«Os vossos clientes têm um processo automatizado para atualizar o cluster. De cada vez, pode cair um nó. E como o pod de RabbitMQ que corre nesse nó se recusa a terminar por causa da proteção do quórum, não deixa que o drain do nó seja feito. O processo de atualização fica bloqueado.»

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

Soluções:
  1. Reduzir o período de tolerância de encerramento predefinido antes das janelas de atualização automatizadas e repô-lo depois
  2. Definir um temporizador de vigilância: se um pod não terminar N segundos depois de receber um SIGTERM, forçar a sua eliminação (usar com cautela)
  3. Usar pod disruption budgets (PDBs): um PDB configurado para permitir no máximo um pod indisponível de cada vez garante que o Kubernetes respeita as restrições de quórum durante os drains de nós

Objetivos de resposta a partir de 15 minutos, consoante o plano. Engenheiros seniores designados.

Contacte-nos

O que nunca se deve fazer com pods de RabbitMQ em Kubernetes?

Nunca force a eliminação de um pod de RabbitMQ sem perceber o impacto no quórum. Forçar a eliminação (kubectl delete pod --force --grace-period=0) contorna por completo o hook pre-stop. Se o pod eliminado à força for o líder de quórum de alguma fila, essas filas perdem o quórum de imediato.
Nunca execute dois pods de RabbitMQ no mesmo nó Kubernetes. As regras de anti-afinidade devem impor isto automaticamente, mas confirme que a sua configuração de anti-afinidade está corretamente definida.
Nunca reduza de 3 réplicas para um número inferior sem verificar primeiro 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 for reportada como estando em estado crítico de quórum, aguarde que recupere antes de avançar com a redução.

Considerações sobre armazenamento e monitorização

Cada pod de RabbitMQ precisa de um PersistentVolumeClaim. Para produção:
  • Use uma StorageClass com volumeBindingMode: WaitForFirstConsumer, para garantir que os pods e os respetivos volumes ficam na mesma zona de disponibilidade
  • Recomenda-se vivamente armazenamento SSD ou NVMe — 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 à eliminação dos pods
  • Não use armazenamento partilhado (NFS, sistemas de ficheiros partilhados) para os volumes de dados do RabbitMQ
Métricas essenciais a acompanhar em implementações específicas de Kubernetes:
  • rabbitmq_quorum_queue_stat_voters — verificar que o quórum se mantém entre os nós
  • Número de reinícios dos pods — reinícios frequentes indicam problemas de quórum ou de recursos
  • Capacidade dos PVCs — monitorizar a utilização de disco no PVC de cada pod
  • rabbitmq_node_disk_free — alertar antes de o alarme de disco disparar
Se está a planear uma nova implementação, a migrar um cluster existente para Kubernetes ou a lidar com problemas relacionados com atualizações, contacte o suporte da AceMQ para apoio na arquitetura de implementação ou suporte prático.

As imagens base são uma questão recorrente de cadeia de fornecimento nestas implementações — consulte a segurança das imagens Bitnami e as alternativas empresariais.

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

O RabbitMQ funciona bem em ambos. Os fatores decisivos são quem opera a plataforma e como é o armazenamento por baixo.

  • Quem o opera. Se uma equipa de plataforma já opera cargas de trabalho com estado em Kubernetes, com um operador, PodDisruptionBudgets e atualizações de StatefulSets como rotina diária, o RabbitMQ é mais um StatefulSet. Se a sua equipa de infraestrutura opera bem VMs e o Kubernetes é apenas onde vivem as aplicações sem estado, colocar lá o broker significa que a equipa de mensagens vai aprender os modos de falha do Kubernetes num sistema de produção.
  • Armazenamento. As filas de quórum e os streams fazem fsync a cada lote de escritas. Numa VM com NVMe local, isso fica abaixo de um milissegundo. Em Kubernetes, a predefinição é um PersistentVolume ligado em rede, e cada fsync atravessa a rede de armazenamento. Vemos tipicamente 2 a 5 ms por fsync em armazenamento em bloco na cloud, o que se reflete diretamente na latência dos publisher confirms nas filas de quórum. Existem provisionadores de PVs locais, mas prendem o pod a um nó. O artigo filas clássicas vs filas de quórum explica porque é que as filas de quórum são mais sensíveis a isto do que as filas clássicas.
  • Atualizações. O Kubernetes faz um reinício rolling do StatefulSet, um pod de cada vez, com o operador a aguardar o quórum antes de cada passo. Em VMs, atualiza no próprio local, nó a nó, ao seu ritmo. A versão Kubernetes é mais automatizada e menos tolerante a um pressuposto errado.
  • Domínios de falha. Em Kubernetes, os nós sofrem drain, os pods são despejados e o autoscaler recupera capacidade sem lhe perguntar nada. Um PDB e a anti-afinidade de pods são a única coisa entre um drain de rotina e um quórum perdido. As VMs falham menos vezes e em calendários que controla, mas falham com mais estrondo, sem nenhum scheduler para reiniciar o broker noutro lado.
  • Rede. Os pods recebem hostnames do headless service e IPs que mudam a cada reinício. Os clientes ligam-se através de um Service ou de um ingress e têm de se voltar a ligar de forma limpa, porque vão ser religados. Tudo o que fixe o IP de um broker deixa de funcionar. Em VMs, os hostnames mantêm-se estáveis durante anos e os bugs de reconexão dos clientes ficam escondidos.
  • Licenciamento. O Tanzu RabbitMQ, a distribuição comercial, é empacotado primeiro para Kubernetes, com uma imagem para VM a par. O RabbitMQ open source corre em qualquer lado.

A nossa recomendação: VMs quando a equipa é pequena e predominam cargas de trabalho de filas de quórum sensíveis à latência. Kubernetes quando há uma equipa de plataforma, um operador em uso e o resto do ambiente já lá vive. Nos nossos projetos, a divisão é aproximadamente equilibrada, e as implementações em Kubernetes que correm mal são quase sempre as que foram adotadas porque o Kubernetes estava disponível, e não porque alguém estivesse preparado para operar nele cargas de trabalho com estado.

Operador, Helm chart ou StatefulSet feito à mão

O RabbitMQ Cluster Kubernetes Operator é a opção mantida upstream e a que usamos por predefinição. Declara um recurso RabbitmqCluster e o operador cria o StatefulSet, o headless service para a descoberta de pares, o Service para os clientes, os Secrets do cookie Erlang e do utilizador predefinido e a configuração do servidor. Trata dos reinícios rolling com um hook preStop que aguarda quórum mais um antes de desligar um nó e configura o TLS a partir de um Secret que lhe indique. Não cria por si um PodDisruptionBudget; acrescente um com maxUnavailable: 1. A par dele, o Messaging Topology Operator transforma utilizadores, vhosts, permissões, filas, exchanges, bindings, políticas, shovels e upstreams de Federation em CRDs, para que a topologia viva no Git junto à definição do cluster.

Um cluster mínimo com forma 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, retire a linha cluster_partition_handling: a 4.3.0 removeu as estratégias de tratamento de partições e a chave não tem qualquer efeito. Mantenha os requests iguais aos limits. O operador deriva o override de memória do RabbitMQ a partir da definição de memória do pod, para que o high watermark e o limite do cgroup coincidam. Acrescente spec.affinity com anti-afinidade de pods entre nós, ou entre zonas, se as tiver.

  • Os Helm charts da comunidade geram, com um único helm install, um StatefulSet mais os services, a configuração e os secrets. Servem para pôr um cluster a funcionar. Não fazem nada depois da instalação: nenhuma atualização rolling ordenada que aguarde o quórum, nenhuma gestão da topologia, e cada helm upgrade reescreve o StatefulSet e espera que corra bem. Se normaliza tudo em Helm, execute o operador e faça a gestão do recurso RabbitmqCluster com um chart.
  • Um StatefulSet feito à mão é defensável em dois casos: um cluster onde não lhe é permitido instalar CRDs ou operadores com âmbito de cluster, ou uma equipa que já tem um padrão de StatefulSet robusto para outros sistemas com estado e quer que o RabbitMQ o siga. O que assume é tudo o que foi descrito acima: configuração da descoberta de pares, o hook preStop de drain, afinação das probes, rotação de secrets e a coreografia das atualizações. O bug recorrente que herdamos é uma atualização que reiniciou dois pods ao mesmo tempo.

Os modos de falha em Kubernetes para os quais nos chamam

  • Um drain levou o líder de quórum, e o PDB deixou. Sintoma: os publishers ficam bloqueados à espera de confirms durante 10 a 30 segundos numa atualização de nó de rotina, ou uma fila reporta que não tem líder porque duas das três réplicas estão em baixo. Causa: inexistência de PDB, ou um que permite mais do que um pod indisponível, combinada com uma atualização do cluster que faz drain dos nós mais depressa do que as filas de quórum conseguem reeleger líderes e recuperar o atraso. Correção: um PDB com maxUnavailable: 1, anti-afinidade de pods para que as réplicas nunca partilhem um nó e o hook preStop do operador (ou o seu próprio rabbitmq-upgrade await_online_quorum_plus_one) para que o drain aguarde.
  • Reassociação do PV após a falha de um nó. Sintoma: depois de um nó morrer, o seu pod de RabbitMQ fica em ContainerCreating com um erro Multi-Attach ou um conflito de afinidade de nó do volume durante seis minutos ou mais. Causa: o armazenamento em bloco associado a uma zona só pode ser ligado na sua própria zona, e a ligação do nó morto só é libertada quando o node controller desiste dele. Correção: o cluster mantém-se de pé com duas de três réplicas se a anti-afinidade as tiver distribuído, por isso não lute contra isto. Use uma storage class WaitForFirstConsumer para que o volume fique na zona do pod e trate a janela de reassociação como um custo conhecido do armazenamento em rede.
  • OOM-killed antes do controlo de fluxo. Sintoma: um pod reinicia com o código de saída 137 e nenhum erro do RabbitMQ no log; o alarme de memória nunca disparou. Causa: o limite de memória do contentor está abaixo do ponto em que o high watermark entraria em ação, ou porque o RabbitMQ leu a memória do host em vez do limite do cgroup, ou porque o watermark não deixa margem para os alocadores e o binary heap da VM Erlang. Correção: requests iguais aos limits, um watermark que fique 20 a 30 por cento abaixo do limite e rabbitmq-diagnostics memory_breakdown para confirmar que o total visto 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 do índice antes de o kubelet a matar. Causa: uma liveness probe que executa rabbitmq-diagnostics check_running ou semelhante falha enquanto o nó reproduz o Mnesia ou o Khepri e reconstrói os índices das filas, o que, num nó grande, demora mais do que o limiar de falha da probe. Correção: uma startup probe com um failureThreshold generoso, uma readiness probe apenas na porta 5672 e nenhuma liveness probe agressiva. O operador é distribuído sem liveness probe precisamente por esta razão.
  • Uma alteração de DNS ou do headless service partiu a descoberta de pares. Sintoma: os pods arrancam, mas cada um forma um cluster de um só, ou recusam-se a arrancar 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, por isso 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 for inevitável, trate-o como uma migração para um novo cluster: exporte as definições, use Shovel ou esvazie as filas e passe os clientes para o novo cluster.

Para a lista mais alargada do que falha quando as mensagens chegam ao Kubernetes, consulte o que falha com mensagens em Kubernetes. Para saber o que vigiar para que estes problemas cheguem como alertas e não como tickets, consulte monitorização de RabbitMQ em Kubernetes. Se preferir alguém que já resolveu estes problemas antes, conheça a nossa consultoria em Kubernetes e contentores e o nosso suporte RabbitMQ.

A sequência completa — se o Kubernetes é o sítio certo, o Operator, as storage classes, as network policies, requests e limits, a monitorização e as atualizações rolling — está no guia de RabbitMQ em Kubernetes.

Perguntas frequentes

O RabbitMQ deve correr em Kubernetes ou em máquinas virtuais?

Ambas as opções funcionam. Execute-o em VMs quando a equipa é pequena, a carga de trabalho assenta em filas de quórum (quorum queues) ou streams com requisitos apertados de latência dos publisher confirms e ainda não opera cargas de trabalho com estado em Kubernetes. Execute-o em Kubernetes quando há uma equipa de plataforma, usa o Cluster Operator e as aplicações que comunicam com ele já lá vivem. O armazenamento é a questão que dói: os volumes ligados em rede acrescentam milissegundos a cada fsync, e as filas de quórum fazem fsync constantemente. Operamos as duas opções para clientes. Nenhuma está errada por si só; o erro é escolher Kubernetes sem ninguém preparado para o operar.

Que operador Kubernetes para RabbitMQ devemos usar?

O RabbitMQ Cluster Kubernetes Operator, mantido upstream pela equipa do RabbitMQ, em conjunto com o Messaging Topology Operator. O Cluster Operator gere o recurso RabbitmqCluster: StatefulSet, services, secrets, configuração, TLS e reinícios rolling que respeitam o quórum. O Topology Operator gere utilizadores, vhosts, filas, exchanges, bindings e políticas como recursos Kubernetes, para que a topologia viva no Git. Acrescente o seu próprio PodDisruptionBudget. Os Helm charts servem para uma primeira instalação, mas não gerem nada depois dela. Um StatefulSet feito à mão só faz sentido onde não são permitidos CRDs.

O RabbitMQ funciona bem em OpenShift?

Sim. Operamos RabbitMQ em OpenShift para clientes empresariais, a par de EKS, AKS e GKE. O Cluster Operator instala-se a partir do OperatorHub, e os seus pods correm sob a SCC restricted desde que o security context do pod fique a cargo do OpenShift, em vez de ser definido pelo operador, o que o spec.override permite. O que difere do Kubernetes vanilla são as Routes em vez de Ingress para AMQP sobre TLS, as permissões de volumes determinadas pela SCC e o ritmo próprio de atualização dos nós do OpenShift, que torna as recomendações de PDB e anti-afinidade acima obrigatórias, e não apenas desejáveis.

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

Três, distribuídas por nós e, idealmente, por zonas, com anti-afinidade de pods. Três réplicas toleram uma perda mantendo a maioria nas filas de quórum, e uma perda é o que um drain, a falha de um nó ou um passo de atualização produzem. Cinco só compensam quando é obrigatório sobreviver ao mesmo tempo a uma falha de zona e a uma operação de manutenção. Nunca duas: as filas de quórum precisam de maioria, e dois nós perdem-na com qualquer falha isolada. Escalar o débito é uma questão separada do número de réplicas, e o artigo HA, DR e dimensionamento de clusters trata do dimensionamento.

Consulta gratuita

Peça a um especialista que analise o seu cluster RabbitMQ

Quer esteja a resolver um incidente em produção, a planear uma migração ou queira uma segunda opinião sobre a sua arquitetura, a nossa equipa está pronta. Sem discursos de vendas, apenas respostas.

Enviar e-mail