Nesta página
Como implementar RabbitMQ em Kubernetes?
- 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
O que é o período de tolerância de encerramento e porque é importante?
«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?
kubectl patch rabbitmqcluster <cluster-name> -n <namespace> \
--type merge \
-p '{"spec": {"terminationGracePeriodSeconds": 30}}'kubectl patch rabbitmqcluster <cluster-name> -n <namespace> \
--type merge \
-p '{"spec": {"replicas": 0}}'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?
«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
- Reduzir o período de tolerância de encerramento predefinido antes das janelas de atualização automatizadas e repô-lo depois
- 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)
- 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
O que nunca se deve fazer com pods de RabbitMQ em Kubernetes?
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.kubectl exec -n <namespace> <rabbitmq-pod> -- rabbitmq-diagnostics check_running
kubectl exec -n <namespace> <rabbitmq-pod> -- rabbitmq-queues check_if_node_is_quorum_criticalConsiderações sobre armazenamento e monitorizaçã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
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
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 = 5GBNo 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 cadahelm upgradereescreve o StatefulSet e espera que corra bem. Se normaliza tudo em Helm, execute o operador e faça a gestão do recursoRabbitmqClustercom 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ópriorabbitmq-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
WaitForFirstConsumerpara 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_breakdownpara 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_runningou 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.