RabbitMQ

Eseguire RabbitMQ su Kubernetes e OpenShift: guida pratica al deployment

Scott Sternloff

Di Scott Sternloff, Enterprise Architect senior

LinkedIn · Aggiornato il

K8sStatefulSet · 3 ReplicasKubernetes & OpenShift
In questa pagina
Eseguire RabbitMQ su Kubernetes o OpenShift è sempre più comune, e sempre più spesso è fonte di sorprese operative per i team convinti che Kubernetes gestirà da solo la complessità. Non è così, almeno non senza capire come i meccanismi di quorum di RabbitMQ interagiscono con la gestione del ciclo di vita dei pod in Kubernetes.
Questa guida illustra i principali pattern di deployment, le insidie specifiche che causano incidenti in produzione e come strutturare il deployment di RabbitMQ su Kubernetes per un funzionamento affidabile.

Come si esegue il deployment di RabbitMQ su Kubernetes?

L'approccio standard è il RabbitMQ Cluster Operator, l'operator Kubernetes ufficiale mantenuto da Broadcom. L'operator si occupa di:
  • Distribuire RabbitMQ come StatefulSet, con una corretta denominazione dei pod e identità di rete stabili
  • Gestire i PersistentVolumeClaim (PVC) per lo storage dei dati di ciascun nodo del cluster
  • Gestire l'appartenenza al cluster, il rilevamento dei nodi e l'Erlang cookie
  • Fornire una custom resource RabbitmqCluster per la configurazione dichiarativa del cluster
Su OpenShift lo stesso operator funziona con una configurazione aggiuntiva delle SCC (Security Context Constraint). AceMQ supporta anche deployment su RKE2, AKS, ACK e altre distribuzioni Kubernetes gestite.
Configurazione minima del cluster: tre nodi, ciascuno su un worker node Kubernetes separato (imposto tramite regole di pod anti-affinity). Eseguire due pod RabbitMQ sullo stesso worker node vanifica l'alta disponibilità.

Che cos'è il termination grace period e perché è importante?

Il RabbitMQ Cluster Operator include un hook pre-stop con un termination grace period predefinito di 604.800 secondi (una settimana). Non è un errore: è un meccanismo di sicurezza.
Prima che un pod RabbitMQ si arresti, l'hook pre-stop verifica se qualche coda il cui leader si trova su quel pod è in stato quorum-critical, ovvero se l'arresto del pod porterebbe una o più code sotto il quorum. Se la condizione è vera, il pod rifiuta di terminare finché il quorum non viene ripristinato.

"L'hook pre-stop verifica che nessuna coda sia in stato quorum-critical prima di consentire al pod di uscire. Protegge il quorum. Ma quando si passa da tre a zero repliche si crea un deadlock: arrestare un pod rende critico il quorum, il che impedisce a quel pod di terminare, il che impedisce al cluster di arrestarsi."

— Scott Sternloff, Principal Architect di AceMQ, sessione di lavoro con Adeptia, aprile 2026

Come si scala in sicurezza a zero un cluster RabbitMQ su Kubernetes?

La procedura sicura per scalare a zero richiede due passaggi eseguiti in sequenza, non contemporaneamente:
Passaggio 1: ridurre il termination grace period a 30 secondi:
kubectl patch rabbitmqcluster <cluster-name> -n <namespace> \
  --type merge \
  -p '{"spec": {"terminationGracePeriodSeconds": 30}}'
Passaggio 2: una volta applicata la modifica, scalare le repliche a zero:
kubectl patch rabbitmqcluster <cluster-name> -n <namespace> \
  --type merge \
  -p '{"spec": {"replicas": 0}}'
Quando si riavvia il cluster, ripristinare il grace period al valore predefinito:
kubectl patch rabbitmqcluster <cluster-name> -n <namespace> \
  --type merge \
  -p '{"spec": {"replicas": 3, "terminationGracePeriodSeconds": 604800}}'

Che cosa succede quando un nodo Kubernetes viene svuotato durante l'upgrade del cluster?

Quando l'upgrade di un cluster Kubernetes esegue il drain di un nodo, i pod su quel nodo vengono terminati. Se sul nodo svuotato gira un pod RabbitMQ le cui code sono quorum-critical, il pod resta bloccato nello stato di terminazione: blocca il drain del nodo, blocca l'upgrade e richiede un intervento manuale.

"I vostri clienti hanno un processo automatizzato per aggiornare il cluster. Un nodo alla volta può andare giù. E poiché il pod RabbitMQ in esecuzione su quel nodo rifiuta di terminare per via della protezione del quorum, il drain del nodo non viene consentito. Il processo di upgrade si blocca."

— Scott Sternloff, Principal Architect di AceMQ, sessione con Adeptia, aprile 2026

Soluzioni:
  1. Ridurre il termination grace period predefinito prima delle finestre di upgrade automatizzate e ripristinarlo al termine
  2. Impostare un timer di watchdog: se un pod non è terminato entro N secondi dalla ricezione di un SIGTERM, forzarne l'eliminazione (con cautela)
  3. Usare i pod disruption budget (PDB): un PDB che consente al massimo un pod non disponibile alla volta fa sì che Kubernetes rispetti i vincoli di quorum durante il drain dei nodi

Obiettivi di risposta da 15 minuti, in base al piano. Ingegneri senior dedicati.

Contattateci

Che cosa non bisogna mai fare con i pod RabbitMQ su Kubernetes?

Mai forzare l'eliminazione di un pod RabbitMQ senza averne compreso l'impatto sul quorum. L'eliminazione forzata (kubectl delete pod --force --grace-period=0) aggira completamente l'hook pre-stop. Se il pod eliminato è il leader del quorum per una qualsiasi coda, quelle code perdono immediatamente il quorum.
Mai eseguire due pod RabbitMQ sullo stesso nodo Kubernetes. Le regole di anti-affinity dovrebbero impedirlo automaticamente, ma verificate che la configurazione di anti-affinity sia impostata correttamente.
Mai scalare da 3 repliche a un numero inferiore senza aver prima verificato lo stato del quorum.
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 qualche coda risulta quorum-critical, attendete che si ristabilisca prima di procedere con la riduzione delle repliche.

Considerazioni su storage e monitoraggio

Ogni pod RabbitMQ richiede un PersistentVolumeClaim. In produzione:
  • Usate una StorageClass con volumeBindingMode: WaitForFirstConsumer, così che i pod e i relativi volumi finiscano nella stessa availability zone
  • Lo storage SSD o NVMe è fortemente consigliato: le scritture nel WAL delle code quorum sono sensibili alla latenza
  • Impostate la retention policy dei PVC su Retain, così che i dati sopravvivano all'eliminazione dei pod
  • Non usate storage condiviso (NFS, file system condivisi) per i volumi dati di RabbitMQ
Metriche chiave da monitorare nei deployment specifici per Kubernetes:
  • rabbitmq_quorum_queue_stat_voters: verifica che il quorum sia mantenuto tra i nodi
  • Numero di riavvii dei pod: riavvii frequenti indicano problemi di quorum o di risorse
  • Capacità dei PVC: monitorate l'utilizzo del disco sul PVC di ciascun pod
  • rabbitmq_node_disk_free: genera un alert prima che scatti l'allarme disco
Se state pianificando un nuovo deployment, migrando un cluster esistente su Kubernetes o affrontando problemi legati agli upgrade, contattate il supporto AceMQ per l'architettura di deployment o per un supporto operativo diretto.

Le immagini di base sono una questione ricorrente di supply chain in questi deployment: si veda la sicurezza delle immagini Bitnami e le alternative enterprise.

RabbitMQ su Kubernetes o su macchine virtuali: come decidere

RabbitMQ funziona bene in entrambi i casi. I fattori decisivi sono chi gestisce la piattaforma e com'è fatto lo storage sottostante.

  • Chi lo gestisce. Se un platform team gestisce già carichi stateful su Kubernetes, con un operator, PodDisruptionBudget e upgrade degli StatefulSet come routine quotidiana, RabbitMQ è solo uno StatefulSet in più. Se il vostro team infrastrutturale gestisce bene le VM e Kubernetes ospita solo le applicazioni stateless, collocarvi il broker significa che il team di messaging imparerà le modalità di guasto di Kubernetes su un sistema di produzione.
  • Storage. Code quorum e stream eseguono fsync a ogni batch di scritture. Su una VM con NVMe locale ciò richiede meno di un millisecondo. Su Kubernetes l'impostazione predefinita è un PersistentVolume collegato via rete, e ogni fsync attraversa la rete di storage. Sullo storage a blocchi in cloud rileviamo in genere da 2 a 5 ms per fsync, che si traducono direttamente in latenza dei publisher confirm sulle code quorum. Esistono provisioner di PV locali, ma vincolano il pod a un nodo. Code classic e code quorum a confronto spiega perché le code quorum sono più sensibili a questo aspetto rispetto alle code classic.
  • Upgrade. Kubernetes esegue un riavvio progressivo dello StatefulSet, un pod alla volta, con l'operator che attende il quorum prima di ogni passaggio. Sulle VM si aggiorna sul posto, nodo per nodo, secondo la propria pianificazione. La versione Kubernetes è più automatizzata e meno tollerante verso un presupposto errato.
  • Domini di guasto. Su Kubernetes i nodi vengono svuotati, i pod vengono sfrattati e l'autoscaler recupera capacità senza chiedere nulla. Un PDB e la pod anti-affinity sono l'unica protezione tra un drain di routine e la perdita del quorum. Le VM si guastano meno spesso e secondo tempistiche che controllate voi, ma quando si guastano l'impatto è maggiore, perché non c'è uno scheduler che riavvii il broker altrove.
  • Rete. I pod ricevono hostname dal headless service e IP che cambiano a ogni riavvio. I client si connettono tramite un Service o un ingress e devono riconnettersi in modo pulito, perché verranno riconnessi. Qualsiasi cosa che fissi l'IP di un broker si rompe. Sulle VM gli hostname restano stabili per anni e i bug di riconnessione dei client rimangono nascosti.
  • Licenze. Tanzu RabbitMQ, la distribuzione commerciale, è pacchettizzata innanzitutto per Kubernetes, con un'immagine per VM a fianco. RabbitMQ open source gira ovunque.

La nostra raccomandazione: VM quando il team è piccolo e prevalgono carichi su code quorum sensibili alla latenza; Kubernetes quando c'è un platform team, un operator già in uso e il resto dell'infrastruttura risiede già lì. Nei nostri progetti la ripartizione è più o meno equa, e i deployment su Kubernetes che vanno male sono quasi sempre quelli adottati perché Kubernetes era disponibile, non perché qualcuno fosse pronto a gestirvi carichi stateful.

Operator, chart Helm o StatefulSet scritto a mano

Il RabbitMQ Cluster Kubernetes Operator è l'opzione mantenuta upstream ed è quella che adottiamo come impostazione predefinita. Si dichiara una risorsa RabbitmqCluster e l'operator crea lo StatefulSet, il headless service per il peer discovery, il Service per i client, i Secret con l'Erlang cookie e l'utente predefinito, e la configurazione del server. Gestisce i riavvii progressivi con un hook preStop che attende il quorum più uno prima di arrestare un nodo, e configura TLS a partire da un Secret indicato. Non crea autonomamente un PodDisruptionBudget: aggiungetene uno con maxUnavailable: 1. Accanto a esso, il Messaging Topology Operator trasforma utenti, vhost, permessi, code, exchange, binding, policy, shovel e upstream di federation in CRD, così la topologia risiede in Git accanto alla definizione del cluster.

Un cluster minimo, con un'impostazione da produzione:

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

Su RabbitMQ 4.3 e versioni successive eliminate la riga cluster_partition_handling: la 4.3.0 ha rimosso le strategie di gestione delle partizioni e la chiave non ha alcun effetto. Mantenete le request uguali ai limit. L'operator ricava l'override di memoria di RabbitMQ dall'impostazione di memoria del pod, così high watermark e limite del cgroup coincidono. Aggiungete spec.affinity con pod anti-affinity tra i nodi, oppure tra le zone se disponibili.

  • I chart Helm della community generano da template uno StatefulSet con service, configurazione e secret in un unico helm install. Vanno bene per avviare un cluster. Dopo l'installazione non fanno nulla: nessun upgrade progressivo ordinato che attenda il quorum, nessuna gestione della topologia, e ogni helm upgrade riscrive lo StatefulSet sperando che vada bene. Se avete standardizzato tutto su Helm, eseguite l'operator e gestite la risorsa RabbitmqCluster con un chart.
  • Uno StatefulSet scritto a mano è giustificabile in due casi: un cluster in cui non è consentito installare CRD o operator con scope di cluster, oppure un team che dispone già di un pattern di StatefulSet consolidato per altri sistemi stateful e vuole che RabbitMQ vi si allinei. In questo caso vi fate carico di tutto quanto descritto sopra: configurazione del peer discovery, hook preStop per il drain, tuning delle probe, rotazione dei secret e la coreografia degli upgrade. Il bug ricorrente che ereditiamo è un upgrade che ha riavviato due pod contemporaneamente.

Le modalità di guasto su Kubernetes per cui veniamo chiamati

  • Un drain ha colpito il leader del quorum e il PDB lo ha permesso. Sintomo: durante un normale upgrade dei nodi i publisher restano bloccati sui confirm per 10-30 secondi, oppure una coda risulta senza leader perché due repliche su tre sono giù. Causa: nessun PDB, o un PDB che consente più di un pod non disponibile, insieme a un upgrade del cluster che svuota i nodi più velocemente di quanto le code quorum riescano a rieleggere il leader e riallinearsi. Soluzione: un PDB con maxUnavailable: 1, pod anti-affinity in modo che le repliche non condividano mai un nodo, e l'hook preStop dell'operator (o un vostro rabbitmq-upgrade await_online_quorum_plus_one) così che il drain attenda.
  • Ricollegamento del PV dopo il guasto di un nodo. Sintomo: dopo la caduta di un nodo, il suo pod RabbitMQ resta in ContainerCreating con un errore Multi-Attach o un conflitto di node affinity del volume per sei minuti o più. Causa: lo storage a blocchi legato a una zona può essere collegato solo nella propria zona, e il collegamento del nodo caduto non viene rilasciato finché il node controller non lo dà per perso. Soluzione: se l'anti-affinity ha distribuito le repliche, il cluster resta attivo con due repliche su tre, quindi non va forzato. Usate una storage class WaitForFirstConsumer, così il volume viene creato nella zona del pod, e considerate la finestra di ricollegamento un costo noto dello storage di rete.
  • OOM kill prima del flow control. Sintomo: un pod si riavvia con exit code 137 senza alcun errore di RabbitMQ nel log; l'allarme di memoria non è mai scattato. Causa: il limite di memoria del container è inferiore alla soglia alla quale interverrebbe l'high watermark, o perché RabbitMQ ha letto la memoria dell'host anziché il limite del cgroup, o perché il watermark non lascia margine per gli allocator e il binary heap della VM Erlang. Soluzione: request uguali ai limit, un watermark che resti dal 20 al 30 percento sotto il limite e rabbitmq-diagnostics memory_breakdown per verificare che il totale visto da RabbitMQ corrisponda a quello del pod.
  • Riavvii causati dalla liveness probe durante il recovery. Sintomo: dopo un riavvio non pulito, un nodo con code di grandi dimensioni entra in CrashLoopBackOff, e ogni tentativo avanza un po' di più nella ricostruzione degli indici prima che il kubelet lo termini. Causa: una liveness probe che esegue rabbitmq-diagnostics check_running o simili fallisce mentre il nodo riproduce Mnesia o Khepri e ricostruisce gli indici delle code, operazione che su un nodo grande dura più della soglia di fallimento della probe. Soluzione: una startup probe con un failureThreshold generoso, una readiness probe solo sulla porta 5672 e nessuna liveness probe aggressiva. L'operator viene distribuito senza liveness probe proprio per questo motivo.
  • Una modifica al DNS o al headless service ha interrotto il peer discovery. Sintomo: i pod si avviano ma ognuno forma un cluster a sé, oppure rifiutano di avviarsi perché la directory dei dati appartiene a un nodo con un nome diverso. Causa: i nomi dei nodi derivano dall'hostname del pod e dal headless service, quindi rinominare il service, il namespace o il dominio DNS del cluster cambia il nome di ogni nodo e rende orfani i dati su disco. Soluzione: non rinominate. Se una ridenominazione è inevitabile, trattatela come una migrazione verso un nuovo cluster: esportate le definizioni, usate shovel o svuotate le code, e spostate i client.

Per l'elenco più ampio di ciò che si rompe quando il messaging approda su Kubernetes, si veda cosa si rompe con il messaging su Kubernetes. Per sapere cosa monitorare affinché questi problemi arrivino come alert anziché come ticket, si veda il monitoraggio di RabbitMQ su Kubernetes. Se preferite affidarvi a chi ha già risolto questi problemi, scoprite la nostra consulenza su Kubernetes e container e il supporto RabbitMQ.

La sequenza completa (se Kubernetes sia la collocazione giusta, l'Operator, le storage class, le network policy, request e limit, il monitoraggio e gli aggiornamenti progressivi) è descritta nella guida a RabbitMQ su Kubernetes.

Domande frequenti

Meglio eseguire RabbitMQ su Kubernetes o su macchine virtuali?

Funzionano entrambe le soluzioni. Conviene usare le VM quando il team è piccolo, il carico si basa su code quorum o stream con requisiti stringenti di latenza dei publisher confirm e non gestite già carichi stateful su Kubernetes. Conviene Kubernetes quando c'è un platform team, usate il Cluster Operator e le applicazioni che dialogano con RabbitMQ risiedono già lì. Il nodo critico è lo storage: i volumi collegati via rete aggiungono millisecondi a ogni fsync, e le code quorum eseguono fsync di continuo. Gestiamo entrambe le configurazioni per i nostri clienti. Nessuna delle due è sbagliata in sé; lo è scegliere Kubernetes senza nessuno pronto a gestirlo.

Quale operator Kubernetes per RabbitMQ conviene usare?

Il RabbitMQ Cluster Kubernetes Operator, mantenuto upstream dal team di RabbitMQ, affiancato dal Messaging Topology Operator. Il Cluster Operator gestisce la risorsa RabbitmqCluster: StatefulSet, service, secret, configurazione, TLS e riavvii progressivi che tengono conto del quorum. Il Topology Operator gestisce utenti, vhost, code, exchange, binding e policy come risorse Kubernetes, così la topologia risiede in Git. Aggiungete un vostro PodDisruptionBudget. I chart Helm vanno bene per una prima installazione, ma dopo non gestiscono nulla. Uno StatefulSet scritto a mano ha senso solo dove le CRD non sono consentite.

RabbitMQ funziona bene su OpenShift?

Sì. Eseguiamo RabbitMQ su OpenShift per clienti enterprise, oltre che su EKS, AKS e GKE. Il Cluster Operator si installa da OperatorHub e i suoi pod girano con la SCC restricted, a patto di lasciare il security context dei pod a OpenShift anziché farlo impostare all'operator, cosa che spec.override consente. Rispetto a Kubernetes standard cambiano le Route al posto degli Ingress per AMQP su TLS, i permessi dei volumi determinati dalle SCC e la cadenza di aggiornamento dei nodi propria di OpenShift, che rende le indicazioni su PDB e anti-affinity riportate sopra un requisito irrinunciabile, non un semplice consiglio.

Quante repliche RabbitMQ servono in un cluster Kubernetes?

Tre, distribuite su nodi diversi e, idealmente, su zone diverse tramite pod anti-affinity. Tre repliche tollerano la perdita di una mentre le code quorum mantengono la maggioranza, e una perdita è esattamente ciò che provoca un drain, il guasto di un nodo o un passaggio di upgrade. Cinque repliche valgono la pena solo se occorre sopravvivere contemporaneamente all'interruzione di una zona e a un intervento di manutenzione. Mai due: le code quorum richiedono la maggioranza e con due nodi la si perde a ogni singolo guasto. Scalare il throughput è una questione distinta dal numero di repliche, e il dimensionamento è trattato in HA, DR e dimensionamento del cluster.

Consulenza gratuita

Fate esaminare a un esperto il vostro cluster RabbitMQ

Che stiate risolvendo un incidente in produzione, pianificando una migrazione o cercando un secondo parere sulla vostra architettura, il nostro team è pronto. Nessun discorso commerciale, solo risposte.

Scriveteci