이 페이지의 내용
Kubernetes에 RabbitMQ를 배포하는 방법
- 적절한 파드 이름과 안정적인 네트워크 식별자를 갖춘 StatefulSet으로 RabbitMQ 배포
- 각 클러스터 노드의 데이터 스토리지를 위한 PersistentVolumeClaim(PVC) 관리
- 클러스터 멤버십, 노드 탐색, Erlang 쿠키 처리
- 선언적 클러스터 구성을 위한 RabbitmqCluster 커스텀 리소스 제공
종료 유예 기간이란 무엇이며 왜 중요한가?
"pre-stop 훅은 파드가 종료되기 전에 쿼럼 임계 상태인 큐가 하나도 없는지 확인합니다. 쿼럼을 보호하는 것이죠. 그런데 레플리카를 3개에서 0개로 줄이면 교착 상태가 생깁니다. 파드 하나를 내리면 쿼럼이 임계 상태가 되고, 그래서 그 파드가 종료되지 못하고, 그래서 클러스터가 내려가지 못하는 겁니다."
— Scott Sternloff, AceMQ 수석 아키텍트, Adeptia 프로젝트 세션, 2026년 4월
Kubernetes에서 RabbitMQ 클러스터를 0개로 안전하게 축소하는 방법
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 파드가 쿼럼 보호 때문에 종료를 거부하니, 노드를 드레인할 수 없습니다. 업그레이드 프로세스가 멈춰 버리는 겁니다."
— Scott Sternloff, AceMQ 수석 아키텍트, Adeptia 세션, 2026년 4월
- 자동 업그레이드 작업 시간 전에 기본 종료 유예 기간을 줄이고, 작업 후 원래대로 되돌립니다
- 워치독 타이머를 설정합니다. SIGTERM을 받은 지 N초가 지나도 파드가 종료되지 않으면 강제 삭제합니다(신중하게 사용)
- 파드 중단 예산(PDB)을 사용합니다. 동시에 최대 한 개의 파드만 사용 불가 상태가 되도록 PDB를 설정하면, 노드 드레인 중에도 Kubernetes가 쿼럼 제약을 지킵니다
Kubernetes에서 RabbitMQ 파드에 절대 하지 말아야 할 일
kubectl delete pod --force --grace-period=0)는 pre-stop 훅을 완전히 우회합니다. 강제 삭제되는 파드가 어떤 큐의 쿼럼 리더라면, 그 큐들은 즉시 쿼럼을 잃습니다.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를 사용해 파드와 볼륨이 같은 가용 영역에 배치되도록 합니다
- SSD나 NVMe 스토리지를 강력히 권장합니다. 쿼럼 큐의 WAL 쓰기는 지연 시간에 민감합니다
- 파드를 삭제해도 데이터가 남도록 PVC의 보존 정책을 Retain으로 설정합니다
- RabbitMQ 데이터 볼륨에 공유 스토리지(NFS, 공유 파일 시스템)를 쓰지 마십시오
rabbitmq_quorum_queue_stat_voters— 노드 전반에서 쿼럼이 유지되는지 확인- 파드 재시작 횟수 — 재시작이 잦다면 쿼럼이나 리소스 문제가 있다는 신호
- PVC 용량 — 각 파드 PVC의 디스크 사용률 모니터링
rabbitmq_node_disk_free— 디스크 알람이 발생하기 전에 경보
이런 배포에서는 베이스 이미지가 공급망 측면에서 반복적으로 문제가 됩니다. Bitnami 이미지 보안과 엔터프라이즈 대안을 참고하십시오.
Kubernetes와 가상 머신 중 RabbitMQ를 어디서 운영할지 결정하는 방법
RabbitMQ는 두 환경 모두에서 잘 동작합니다. 결정 요인은 누가 플랫폼을 운영하는지, 그리고 그 아래 스토리지가 어떤 형태인지입니다.
- 누가 운영하는가. 플랫폼 팀이 이미 Kubernetes에서 스테이트풀 워크로드를 운영하고 있고, 오퍼레이터, PodDisruptionBudget, StatefulSet 업그레이드가 일상 업무라면 RabbitMQ는 StatefulSet 하나가 더 늘어나는 것일 뿐입니다. 인프라 팀이 VM은 잘 운영하지만 Kubernetes에는 스테이트리스 앱만 있다면, 브로커를 그곳에 두는 것은 메시징 팀이 운영 시스템에서 Kubernetes의 장애 유형을 배운다는 뜻입니다.
- 스토리지. 쿼럼 큐와 스트림은 쓰기 배치마다 fsync를 합니다. 로컬 NVMe를 쓰는 VM에서는 1밀리초도 걸리지 않습니다. Kubernetes의 기본값은 네트워크 연결 PersistentVolume이므로 fsync마다 스토리지 네트워크를 거칩니다. 클라우드 블록 스토리지에서는 보통 fsync당 2~5ms가 걸리며, 이는 쿼럼 큐의 publisher confirm 지연으로 그대로 나타납니다. 로컬 PV 프로비저너도 있지만 파드를 특정 노드에 고정시킵니다. 쿼럼 큐가 클래식 큐보다 이 부분에 더 민감한 이유는 클래식 큐와 쿼럼 큐 비교에서 다룹니다.
- 업그레이드. Kubernetes는 StatefulSet을 한 번에 파드 하나씩 롤링 재시작하며, 오퍼레이터가 단계마다 쿼럼을 기다립니다. VM에서는 원하는 일정에 맞춰 노드별로 제자리 업그레이드를 합니다. Kubernetes 쪽이 더 자동화되어 있지만, 잘못된 가정에는 더 가혹합니다.
- 장애 도메인. Kubernetes에서는 노드가 드레인되고, 파드가 축출되며, 오토스케일러가 묻지도 않고 용량을 회수합니다. 일상적인 드레인과 쿼럼 손실 사이를 막아 주는 것은 PDB와 파드 안티 어피니티뿐입니다. VM은 장애가 덜 잦고 직접 통제하는 일정에 따라 내려가지만, 한번 장애가 나면 브로커를 다른 곳에서 재시작해 줄 스케줄러가 없어 타격이 더 큽니다.
- 네트워킹. 파드는 헤드리스 서비스로부터 호스트 이름을 받고, 재시작할 때마다 IP가 바뀝니다. 클라이언트는 Service나 인그레스를 통해 연결하며, 재연결은 반드시 일어나므로 깔끔하게 재연결할 수 있어야 합니다. 브로커 IP를 고정해 둔 것은 모두 깨집니다. VM에서는 호스트 이름이 몇 년씩 그대로이므로 클라이언트 재연결 버그도 숨어 있습니다.
- 라이선스. 상용 배포판인 Tanzu RabbitMQ는 Kubernetes용으로 먼저 패키징되며, VM 이미지도 함께 제공됩니다. 오픈소스 RabbitMQ는 어디서나 실행됩니다.
AceMQ의 권장 사항: 팀 규모가 작고 지연에 민감한 쿼럼 큐 워크로드가 대부분이라면 VM, 플랫폼 팀이 있고 오퍼레이터를 사용 중이며 나머지 환경이 이미 Kubernetes에 있다면 Kubernetes입니다. AceMQ가 맡은 프로젝트에서는 대략 반반으로 나뉘며, 잘못 흘러가는 Kubernetes 배포는 거의 항상 누군가 스테이트풀 워크로드를 운영할 준비가 되어서가 아니라 단지 Kubernetes가 있었기 때문에 도입한 경우입니다.
오퍼레이터, Helm 차트, 직접 작성한 StatefulSet
RabbitMQ Cluster Kubernetes Operator는 업스트림에서 유지보수하는 방식이며, AceMQ가 기본으로 선택하는 방식입니다. RabbitmqCluster 리소스를 선언하면 오퍼레이터가 StatefulSet, 피어 탐색을 위한 헤드리스 서비스, 클라이언트용 Service, Erlang 쿠키와 기본 사용자 Secret, 서버 설정을 생성합니다. 노드를 내리기 전에 쿼럼 플러스 원(quorum-plus-one)을 기다리는 preStop 훅으로 롤링 재시작을 처리하며, 지정한 Secret으로 TLS를 연결합니다. PodDisruptionBudget은 스스로 만들지 않으므로 maxUnavailable: 1로 직접 추가하십시오. 이와 함께 Messaging Topology Operator는 사용자, vhost, 권한, 큐, 익스체인지, 바인딩, 정책, shovel, 페더레이션 업스트림을 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 = 5GBRabbitMQ 4.3 이상에서는 cluster_partition_handling 줄을 삭제하십시오. 4.3.0에서 파티션 처리 전략이 제거되어 이 키는 아무 효과가 없습니다. requests와 limits는 같게 유지하십시오. 오퍼레이터는 파드의 메모리 설정에서 RabbitMQ의 메모리 오버라이드 값을 도출하므로, high watermark와 cgroup 한도가 일치하게 됩니다. 노드 간, 또는 영역이 있다면 영역 간 파드 안티 어피니티를 담은 spec.affinity를 추가하십시오.
- 커뮤니티 Helm 차트는
helm install한 번으로 StatefulSet과 서비스, 설정, 시크릿을 템플릿으로 만들어 줍니다. 클러스터를 띄우는 데는 괜찮습니다. 하지만 설치 후에는 아무것도 하지 않습니다. 쿼럼을 기다리며 순서대로 진행하는 롤링 업그레이드도, 토폴로지 관리도 없으며,helm upgrade를 할 때마다 StatefulSet을 다시 쓰고 무사하기를 바랄 뿐입니다. 모든 것을 Helm으로 표준화했다면, 오퍼레이터를 실행하고RabbitmqCluster리소스를 차트로 관리하십시오. - 직접 작성한 StatefulSet이 타당한 경우는 두 가지입니다. CRD나 클러스터 범위 오퍼레이터를 설치할 수 없는 클러스터, 또는 다른 스테이트풀 시스템에 이미 검증된 StatefulSet 패턴이 있어 RabbitMQ도 그에 맞추려는 팀입니다. 대신 앞에서 말한 모든 것을 직접 떠안게 됩니다. 피어 탐색 설정, preStop 드레인 훅, 프로브 튜닝, 시크릿 교체, 업그레이드 절차까지입니다. AceMQ가 이런 환경을 넘겨받을 때 반복해서 보는 버그는 파드 두 개를 한꺼번에 재시작한 업그레이드입니다.
AceMQ가 호출받는 Kubernetes 장애 유형
- 드레인이 쿼럼 리더를 내렸고, PDB가 그것을 허용했습니다. 증상: 일상적인 노드 업그레이드 중 퍼블리셔가 confirm을 기다리며 10~30초간 막히거나, 레플리카 세 개 중 두 개가 다운되어 큐에 리더가 없다고 보고됩니다. 원인: PDB가 없거나 두 개 이상의 파드가 동시에 사용 불가 상태가 되도록 허용하는 PDB에, 쿼럼 큐가 리더를 다시 선출하고 따라잡는 속도보다 빠르게 노드를 드레인하는 클러스터 업그레이드가 겹친 경우입니다. 해결:
maxUnavailable: 1인 PDB, 레플리카가 노드를 공유하지 않도록 하는 파드 안티 어피니티, 그리고 드레인이 기다리도록 하는 오퍼레이터의 preStop 훅(또는 직접 구성한rabbitmq-upgrade await_online_quorum_plus_one)입니다. - 노드 장애 후 PV 재연결. 증상: 노드가 죽은 뒤 해당 RabbitMQ 파드가 Multi-Attach 오류나 볼륨 노드 어피니티 충돌로 6분 이상 ContainerCreating 상태에 머뭅니다. 원인: 영역에 묶인 블록 스토리지는 자기 영역에서만 연결할 수 있고, 죽은 노드의 연결은 노드 컨트롤러가 그 노드를 포기할 때까지 해제되지 않습니다. 해결: 안티 어피니티로 분산해 두었다면 클러스터는 레플리카 세 개 중 두 개로 계속 동작하므로, 억지로 해결하려 하지 마십시오.
WaitForFirstConsumer스토리지 클래스를 써서 볼륨이 파드의 영역에 배치되도록 하고, 재연결 시간은 네트워크 스토리지의 알려진 비용으로 받아들이십시오. - 플로 컨트롤보다 먼저 OOM으로 종료. 증상: 파드가 종료 코드 137로 재시작되는데 로그에 RabbitMQ 오류가 없고, 메모리 알람도 발생하지 않았습니다. 원인: RabbitMQ가 cgroup 한도 대신 호스트 메모리를 읽었거나, watermark가 Erlang VM의 할당자와 바이너리 힙을 위한 여유를 남기지 않아서, 컨테이너 메모리 한도가 high watermark가 작동할 지점보다 아래에 있습니다. 해결: requests와 limits를 같게 하고, watermark는 한도보다 20~30% 낮게 잡으며,
rabbitmq-diagnostics memory_breakdown으로 RabbitMQ가 인식하는 총량이 파드와 일치하는지 확인합니다. - 복구 중 liveness 프로브로 인한 재시작. 증상: 비정상 재시작 후 큰 큐를 가진 노드가 CrashLoopBackOff에 빠지고, 시도할 때마다 인덱스 재구축이 조금씩 더 진행되다가 kubelet에 의해 종료됩니다. 원인:
rabbitmq-diagnostics check_running같은 명령을 실행하는 liveness 프로브가, 노드가 Mnesia나 Khepri를 재생하고 큐 인덱스를 재구축하는 동안 실패합니다. 큰 노드에서는 이 작업이 프로브의 실패 임계값보다 오래 걸립니다. 해결: failureThreshold를 넉넉히 준 startup 프로브, 5672 포트만 확인하는 readiness 프로브를 쓰고, 공격적인 liveness 프로브는 아예 두지 마십시오. 오퍼레이터가 liveness 프로브 없이 배포되는 이유가 바로 이것입니다. - DNS나 헤드리스 서비스 변경으로 피어 탐색이 깨짐. 증상: 파드는 시작되지만 각자 단일 노드 클러스터를 이루거나, 데이터 디렉터리가 다른 이름의 노드 것이라며 기동을 거부합니다. 원인: 노드 이름은 파드 호스트 이름과 헤드리스 서비스에서 도출되므로, 서비스, 네임스페이스, 클러스터 DNS 도메인의 이름을 바꾸면 모든 노드 이름이 바뀌고 디스크의 데이터가 고아가 됩니다. 해결: 이름을 바꾸지 마십시오. 바꿀 수밖에 없다면 새 클러스터로의 마이그레이션으로 다루십시오. 정의를 내보내고, 큐를 shovel로 옮기거나 비운 다음, 클라이언트를 전환합니다.
메시징을 Kubernetes에 올렸을 때 깨지는 것들의 전체 목록은 Kubernetes 위의 메시징에서 깨지는 것들을 참고하십시오. 이런 문제가 티켓이 아니라 알림으로 먼저 도착하도록 무엇을 지켜봐야 하는지는 RabbitMQ Kubernetes 모니터링에서 다룹니다. 이런 문제를 이미 해결해 본 전문가가 필요하다면 AceMQ의 Kubernetes 및 컨테이너 컨설팅과 RabbitMQ 기술 지원을 확인하십시오.
Kubernetes가 적합한 환경인지부터 오퍼레이터, 스토리지 클래스, 네트워크 정책, requests와 limits, 모니터링, 롤링 업데이트까지 전체 과정은 RabbitMQ on Kubernetes 가이드에서 다룹니다.
자주 묻는 질문
RabbitMQ는 Kubernetes와 가상 머신 중 어디에서 운영해야 하나요?
둘 다 가능합니다. 팀 규모가 작고, 워크로드가 publisher confirm 지연에 민감한 쿼럼 큐나 스트림에 크게 의존하며, Kubernetes에서 스테이트풀 워크로드를 운영해 본 적이 없다면 VM에서 운영하십시오. 플랫폼 팀이 있고, Cluster Operator를 사용하며, RabbitMQ와 통신하는 애플리케이션이 이미 Kubernetes에 있다면 Kubernetes에서 운영하십시오. 발목을 잡는 것은 스토리지입니다. 네트워크 연결 볼륨은 fsync마다 몇 밀리초를 더하는데, 쿼럼 큐는 쉴 새 없이 fsync를 합니다. AceMQ는 고객사를 위해 두 방식을 모두 운영합니다. 어느 쪽도 그 자체로 잘못된 선택은 아닙니다. 잘못된 것은 운영할 준비가 된 사람 없이 Kubernetes를 고르는 것입니다.
어떤 RabbitMQ Kubernetes 오퍼레이터를 써야 하나요?
RabbitMQ 팀이 업스트림에서 유지보수하는 RabbitMQ Cluster Kubernetes Operator와 Messaging Topology Operator를 함께 쓰십시오. Cluster Operator는 RabbitmqCluster 리소스, 즉 StatefulSet, 서비스, 시크릿, 설정, TLS, 쿼럼을 고려한 롤링 재시작을 관리합니다. Topology Operator는 사용자, vhost, 큐, 익스체인지, 바인딩, 정책을 Kubernetes 리소스로 관리하므로 토폴로지를 Git에 둘 수 있습니다. PodDisruptionBudget은 직접 추가하십시오. Helm 차트는 첫 설치에는 괜찮지만 그 이후로는 아무것도 관리하지 않습니다. 직접 작성한 StatefulSet은 CRD를 쓸 수 없는 환경에서만 의미가 있습니다.
RabbitMQ는 OpenShift에서도 잘 동작하나요?
네. AceMQ는 EKS, AKS, GKE와 함께 OpenShift에서도 엔터프라이즈 고객사의 RabbitMQ를 운영합니다. Cluster Operator는 OperatorHub에서 설치하며, 파드 보안 컨텍스트를 오퍼레이터가 설정하지 않고 OpenShift에 맡기면 파드가 restricted SCC로 실행됩니다. 이는 spec.override로 지원됩니다. 일반 Kubernetes와 다른 점은 TLS 기반 AMQP에 Ingress 대신 Route를 쓴다는 것, SCC에 따라 볼륨 권한이 정해진다는 것, 그리고 OpenShift 자체의 노드 업그레이드 주기입니다. 이 때문에 앞서 설명한 PDB와 안티 어피니티 지침은 있으면 좋은 것이 아니라 반드시 지켜야 하는 것이 됩니다.
Kubernetes 클러스터에는 RabbitMQ 레플리카를 몇 개 두어야 하나요?
세 개입니다. 파드 안티 어피니티로 노드에, 가능하다면 영역(zone)에도 분산하십시오. 레플리카가 세 개면 하나를 잃어도 쿼럼 큐가 과반을 유지하며, 드레인, 노드 장애, 업그레이드 단계가 만드는 것이 바로 한 개의 손실입니다. 다섯 개는 영역 장애와 유지보수 작업을 동시에 견뎌야 할 때만 가치가 있습니다. 두 개는 절대 안 됩니다. 쿼럼 큐에는 과반이 필요한데, 노드가 두 개면 어느 하나만 장애가 나도 과반을 잃습니다. 처리량 확장은 레플리카 수와는 별개의 문제이며, 용량 산정은 HA, DR 및 클러스터 규모 산정에서 다룹니다.