本頁內容
如何在 Kubernetes 上部署 RabbitMQ?
- 以 StatefulSet 部署 RabbitMQ,具備正確的 Pod 命名與穩定的網路識別
- 為每個叢集節點的資料儲存管理 PersistentVolumeClaim(PVC)
- 處理叢集成員資格、節點探索與 Erlang cookie
- 提供 RabbitmqCluster 自訂資源,以宣告式的方式設定叢集
什麼是終止寬限期?為什麼它很重要?
「preStop hook 的作用,是在允許 Pod 結束之前,確認沒有任何佇列處於仲裁臨界狀態。它在保護仲裁。但當您把副本從三個降到零時,就會產生死結——因為關掉一個 Pod 會讓仲裁進入臨界狀態,這會阻止該 Pod 終止,進而讓整個叢集無法關閉。」
——Scott Sternloff,AceMQ 首席架構師,Adeptia 專案會議,2026 年 4 月
如何在 Kubernetes 上安全地將 RabbitMQ 叢集縮減到零?
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}}'在叢集升級期間排空 Kubernetes 節點時會發生什麼事?
「您的客戶有一套自動化流程來升級他們的叢集,一次可以讓一個節點下線。而因為執行在該節點上的 RabbitMQ Pod 基於仲裁保護而拒絕終止,它不會讓這個節點被排空,他們的升級流程就卡住了。」
——Scott Sternloff,AceMQ 首席架構師,Adeptia 會議,2026 年 4 月
- 在自動化升級時段之前縮短預設的終止寬限期,並在之後恢復
- 設定看門狗計時器:如果 Pod 在收到 SIGTERM 後 N 秒內仍未終止,就強制刪除它(請謹慎使用)
- 使用 Pod 中斷預算(PDB):設定為一次最多只允許一個 Pod 無法使用的 PDB,可確保 Kubernetes 在排空節點時遵守仲裁限制
在 Kubernetes 上,絕對不該對 RabbitMQ Pod 做哪些事?
kubectl delete pod --force --grace-period=0)會完全繞過 preStop hook。如果被強制刪除的 Pod 是任何佇列的仲裁 leader,那些佇列會立刻失去仲裁。kubectl exec -n <namespace> <rabbitmq-pod> -- rabbitmq-diagnostics check_running
kubectl exec -n <namespace> <rabbitmq-pod> -- rabbitmq-queues check_if_node_is_quorum_critical儲存與監控的考量
- 使用 volumeBindingMode: WaitForFirstConsumer 的 StorageClass,確保 Pod 與其磁碟區落在同一個可用區域
- 強烈建議使用 SSD 或 NVMe 儲存——仲裁佇列的 WAL 寫入對延遲非常敏感
- 將 PVC 的保留政策設為 Retain,讓資料在 Pod 刪除後依然保留
- 不要為 RabbitMQ 資料磁碟區使用共用儲存(NFS、共用檔案系統)
rabbitmq_quorum_queue_stat_voters——確認各節點之間維持仲裁- Pod 重新啟動次數——頻繁重新啟動代表仲裁或資源出了問題
- PVC 容量——監控每個 Pod 的 PVC 磁碟使用率
rabbitmq_node_disk_free——在磁碟警報觸發之前發出警示
在這類部署中,基礎映像檔是一再出現的供應鏈問題——請參閱 Bitnami 映像檔安全性與企業級替代方案。
RabbitMQ 該放在 Kubernetes 還是虛擬機器上:如何決定
RabbitMQ 在兩者上都能運作良好。決定因素在於由誰營運平台,以及底層的儲存是什麼樣子。
- 由誰營運。如果平台團隊早已在 Kubernetes 上營運有狀態工作負載,operator、PodDisruptionBudget 與 StatefulSet 升級都是日常例行工作,那麼 RabbitMQ 只不過是多一個 StatefulSet。如果您的基礎架構團隊擅長營運虛擬機器,而 Kubernetes 只用來放無狀態應用程式,把 broker 放上去,就代表訊息團隊要在正式環境系統上學習 Kubernetes 的各種故障模式。
- 儲存。仲裁佇列與 streams 在每一批寫入時都會執行 fsync。在配備本機 NVMe 的虛擬機器上,這只需要不到一毫秒。在 Kubernetes 上,預設是網路掛載的 PersistentVolume,每一次 fsync 都要穿越儲存網路。我們在雲端區塊儲存上通常看到每次 fsync 需要 2 到 5 毫秒,而這會直接反映在仲裁佇列的發布確認延遲上。本機 PV 佈建工具確實存在,但會把 Pod 綁定在某個節點上。傳統佇列與仲裁佇列比較一文說明了為什麼仲裁佇列比傳統佇列更在意這一點。
- 升級。Kubernetes 會對 StatefulSet 進行滾動重新啟動,一次一個 Pod,operator 在每一步之前都會等待仲裁。在虛擬機器上,您依自己的時程逐一節點原地升級。Kubernetes 的方式更自動化,但對錯誤假設的容忍度也更低。
- 故障域。在 Kubernetes 上,節點會被排空、Pod 會被驅逐,自動擴展器也會在不經您同意的情況下回收容量。在一次例行排空與失去仲裁之間,唯一的屏障就是 PDB 與 Pod 反親和性。虛擬機器較少故障,而且故障時程由您掌控,但一旦故障就更嚴重,因為沒有排程器能在其他地方重新啟動 broker。
- 網路。Pod 的主機名稱來自 headless Service,IP 則在每次重新啟動時都會改變。用戶端透過 Service 或 Ingress 連線,而且必須能乾淨地重新連線,因為它們一定會被重新連線。任何綁定 broker IP 的作法都會失效。在虛擬機器上,主機名稱多年不變,用戶端重新連線的錯誤也因此一直藏而不露。
- 授權。商業發行版 Tanzu RabbitMQ 優先以 Kubernetes 形式封裝,同時也提供虛擬機器映像檔。開源 RabbitMQ 則可以在任何地方執行。
我們的建議:團隊規模小、且以對延遲敏感的仲裁佇列工作負載為主時,選擇虛擬機器。有平台團隊、已在使用 operator,而且其餘系統都已經在 Kubernetes 上時,選擇 Kubernetes。在我們的專案中,兩者的比例大致各半,而結果不理想的 Kubernetes 部署,幾乎都是因為「剛好有 Kubernetes 可用」而採用,而不是因為有人已經準備好在上面營運有狀態工作負載。
Operator、Helm chart,還是自行打造的 StatefulSet
RabbitMQ Cluster Kubernetes Operator 是由上游維護的選項,也是我們的預設選擇。您宣告一個 RabbitmqCluster 資源,operator 就會建立 StatefulSet、用於節點互相探索的 headless Service、用戶端 Service、Erlang cookie 與預設使用者的 Secret,以及伺服器設定。它以 preStop hook 處理滾動重新啟動,在讓節點下線之前等待達到「仲裁數加一」,並從您指定的 Secret 接上 TLS。它不會自行建立 PodDisruptionBudget;請以 maxUnavailable: 1 自行加上。與它搭配的 Messaging Topology Operator,會將使用者、vhost、權限、佇列、交換器、繫結、政策、shovel 與 federation upstream 轉為 CRD,讓拓樸與叢集定義一起存放在 Git 中。
一個最精簡、符合正式環境形態的叢集:
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在 RabbitMQ 4.3 及更新版本中,請移除 cluster_partition_handling 這一行:4.3.0 已移除網路分割處理策略,這個鍵不再有任何作用。請讓 requests 等於 limits。Operator 會依據 Pod 的記憶體設定推導出 RabbitMQ 的記憶體覆寫值,讓高水位線與 cgroup 上限一致。加上 spec.affinity,設定跨節點的 Pod 反親和性;若有多個可用區域,則設定跨可用區域。
- 社群 Helm chart 以一次
helm install,將 StatefulSet 連同 Service、設定與 Secret 一起套用範本建立。用來把叢集架起來沒問題。但安裝之後它什麼都不做:沒有會等待仲裁的有序滾動升級、沒有拓樸管理,而每一次helm upgrade都會改寫 StatefulSet,然後祈禱沒事。如果您所有東西都統一使用 Helm,請改為執行 operator,再用 chart 管理RabbitmqCluster資源。 - 自行打造的 StatefulSet 只在兩種情況下說得過去:不允許安裝 CRD 或叢集範圍 operator 的叢集,或是團隊已經為其他有狀態系統建立了強化過的 StatefulSet 模式,並希望 RabbitMQ 與之一致。您要承擔的就是上述的一切:節點探索設定、preStop 排空 hook、探針調校、Secret 輪替,以及升級的整套編排。我們一再接手的錯誤,就是一次升級同時重新啟動了兩個 Pod。
我們最常被找去處理的 Kubernetes 故障模式
- 排空帶走了仲裁 leader,而 PDB 竟然允許。症狀:在一次例行的節點升級期間,發布端因等待確認而阻塞 10 到 30 秒,或某個佇列因三個副本中有兩個下線而回報沒有 leader。原因:沒有 PDB,或 PDB 允許超過一個 Pod 無法使用,再加上叢集升級排空節點的速度,快過仲裁佇列重新選舉並追上進度的速度。解法:設定
maxUnavailable: 1的 PDB、讓副本永不共用節點的 Pod 反親和性,以及 operator 的 preStop hook(或您自己的rabbitmq-upgrade await_online_quorum_plus_one),讓排空作業等待。 - 節點故障後的 PV 重新掛載。症狀:某個節點故障後,它的 RabbitMQ Pod 停在 ContainerCreating 狀態長達六分鐘以上,並出現 Multi-Attach 錯誤或磁碟區節點親和性衝突。原因:綁定可用區域的區塊儲存只能在自己的可用區域內掛載,而故障節點的掛載要等到節點控制器放棄它之後才會釋放。解法:只要反親和性有把副本分散開來,叢集就能靠三個副本中的兩個繼續運作,所以不必硬碰硬。使用
WaitForFirstConsumer的 storage class,讓磁碟區落在 Pod 所在的可用區域,並把重新掛載的空窗期視為網路儲存的已知成本。 - 在流量控制啟動之前就被 OOM kill。症狀:Pod 以結束代碼 137 重新啟動,日誌中沒有任何 RabbitMQ 錯誤;記憶體警報從未觸發。原因:容器的記憶體上限低於高水位線會啟動的那個點,可能是因為 RabbitMQ 讀取的是主機記憶體而不是 cgroup 上限,或是水位線沒有為 Erlang VM 的配置器與 binary heap 預留餘裕。解法:讓 requests 等於 limits、將水位線設在比上限低 20% 到 30% 的位置,並用
rabbitmq-diagnostics memory_breakdown確認 RabbitMQ 看到的總量與 Pod 相符。 - 復原期間被存活探針重新啟動。症狀:一次非正常重新啟動之後,擁有大型佇列的節點進入 CrashLoopBackOff,每一次嘗試都在索引重建上推進得更遠一些,然後就被 kubelet 終止。原因:執行
rabbitmq-diagnostics check_running或類似指令的存活探針,在節點重播 Mnesia 或 Khepri 並重建佇列索引時失敗,而在大型節點上,這個過程所需的時間超過了探針的失敗門檻。解法:設定 failureThreshold 寬鬆的啟動探針、只針對 5672 埠的就緒探針,並且完全不要使用激進的存活探針。Operator 預設不附存活探針,正是出於這個原因。 - DNS 或 headless Service 的變更破壞了節點探索。症狀:Pod 啟動了,但每個 Pod 各自形成一個只有自己的叢集,或因為資料目錄屬於另一個名稱的節點而拒絕開機。原因:節點名稱是由 Pod 主機名稱與 headless Service 推導而來,因此重新命名 Service、命名空間或叢集 DNS 網域,都會改變每一個節點名稱,讓磁碟上的資料成為孤兒。解法:不要重新命名。如果非改不可,就把它當作遷移到新叢集來處理:匯出定義、以 shovel 搬移或排空佇列,再切換用戶端。
關於訊息系統搬上 Kubernetes 後會出現哪些問題的完整清單,請參閱訊息系統在 Kubernetes 上會出什麼問題。關於該監控哪些項目,讓這些問題以警示而不是支援單的形式出現,請參閱RabbitMQ Kubernetes 監控。如果您希望交給已經修過這些問題的人處理,請參閱我們的Kubernetes 與容器顧問服務,以及 RabbitMQ 技術支援。
完整的步驟——Kubernetes 是否適合、Operator、storage class、網路政策、requests 與 limits、監控與滾動更新——請參閱 RabbitMQ on Kubernetes 指南。
常見問題
RabbitMQ 應該執行在 Kubernetes 上,還是虛擬機器上?
兩者都可行。如果團隊規模小、工作負載仰賴對發布確認(publisher confirm)延遲要求嚴格的仲裁佇列(quorum queues)或 streams,而且您原本就沒有在 Kubernetes 上營運有狀態工作負載,就選擇虛擬機器。如果有平台團隊、您使用 Cluster Operator,而且與它溝通的應用程式本來就在 Kubernetes 上,就選擇 Kubernetes。真正會讓人吃虧的是儲存:網路掛載的磁碟區會讓每一次 fsync 多出數毫秒,而仲裁佇列會不斷執行 fsync。我們同時為客戶營運這兩種環境。兩者本身都沒有錯;錯的是在沒有人準備好營運的情況下選擇 Kubernetes。
我們應該使用哪一個 RabbitMQ Kubernetes operator?
由 RabbitMQ 團隊在上游維護的 RabbitMQ Cluster Kubernetes Operator,搭配 Messaging Topology Operator。Cluster Operator 管理 RabbitmqCluster 資源:StatefulSet、Service、Secret、設定、TLS,以及顧及仲裁的滾動重新啟動。Topology Operator 則將使用者、vhost、佇列、交換器、繫結與政策作為 Kubernetes 資源來管理,讓拓樸存放在 Git 中。請自行加上 PodDisruptionBudget。Helm chart 適合首次安裝,但安裝之後什麼都不管。只有在不允許使用 CRD 的環境中,自行打造的 StatefulSet 才有道理。
RabbitMQ 在 OpenShift 上執行得好嗎?
很好。除了 EKS、AKS 與 GKE,我們也為企業客戶在 OpenShift 上營運 RabbitMQ。Cluster Operator 可以從 OperatorHub 安裝,而只要把 Pod 安全性內容交給 OpenShift 決定、而不是由 operator 設定(spec.override 支援這種作法),它的 Pod 就能在 restricted SCC 下執行。與原生 Kubernetes 不同的地方在於:以 Route 而非 Ingress 承載透過 TLS 的 AMQP、由 SCC 決定的磁碟區權限,以及 OpenShift 自己的節點升級節奏——這使得上述關於 PDB 與反親和性的建議成為非做不可,而不只是錦上添花。
Kubernetes 叢集中的 RabbitMQ 應該有幾個副本?
三個,透過 Pod 反親和性分散在不同節點上,最好也分散在不同的可用區域。三個副本可以容忍失去一個,同時讓仲裁佇列維持多數,而排空(drain)、節點故障或一個升級步驟造成的正是失去一個。只有在必須同時撐過可用區域中斷與維護事件時,五個副本才值得。絕對不要用兩個:仲裁佇列需要多數,而兩個節點在任何單一故障下都會失去多數。傳輸量擴展與副本數量是兩個不同的問題,規模規劃請參閱高可用性、災難復原與叢集規模規劃。