Na tej stronie
Dlaczego aktualizacje RabbitMQ się nie udają?
„Firmy bardzo często mają z tym problem albo o tym zapominają: nie aktualizują regularnie. Czasem aktualizacja zajmuje im kilka lat. A jeśli próbują przejść z obecnej wersji od razu na najnowszą, pojawia się mnóstwo nieprzewidzianych problemów — bo powinny były aktualizować krok po kroku.”
— Jeff Sogolov, inżynier AceMQ, sesja w ramach współpracy z Lucidya, maj 2025
Jaka jest wymagana ścieżka aktualizacji z 3.x do 4.x?
rabbitmqctl enable_feature_flag allA co ze zgodnością z Erlangiem?
- 3.12 obsługuje Erlang 25.x jako minimum
- 3.13 wymaga co najmniej Erlang 26 (zalecany 26.2)
- 4.x również wymaga co najmniej Erlang 26.2
„Erlanga można zaktualizować z 25 bezpośrednio do 26.2. Na 26.2 aktualizuje się RabbitMQ do 3.13 — właściwy Erlang już jest. Potem z 3.13 do 4.1 obowiązuje nadal ta sama wersja Erlanga.”
— Jeff Sogolov, inżynier AceMQ, sesja z Lucidya, maj 2025
Strategia 1: aktualizacja krocząca (w miejscu)
- Zatrzymać węzeł 1 (tylko usługę — nie system operacyjny)
- Zaktualizować Erlanga na węźle 1 do wymaganej wersji
- Zaktualizować RabbitMQ na węźle 1 do wersji docelowej
- Uruchomić usługę RabbitMQ na węźle 1
- Potwierdzić, że węzeł 1 ponownie dołączył do klastra i działa prawidłowo
- Powtórzyć dla węzłów 2 i 3
Strategia 2: wdrożenie blue-green
- Przygotować nowy klaster (green) z docelową wersją RabbitMQ i Erlanga
- Skonfigurować w klastrze green upstream federacji kolejek wskazujący na klaster blue
- W miarę przenoszenia konsumentów do klastra green federacja automatycznie pobiera komunikaty z blue do green
- Gdy wszyscy konsumenci są już w green, przenieść do green producentów
- Po przeniesieniu producentów opróżnić pozostałe komunikaty z blue za pomocą wtyczki Shovel
- Wycofać klaster blue
„Blue-green oznacza zero przestojów. Można to zrobić w dowolnym momencie — bez trybu serwisowego. Kosztem jest to, że przez pewien czas działają dwa klastry, na co nie każdą firmę stać, zwłaszcza on-premises. Ale we wdrożeniach opartych na AWS, gdzie nowe klastry uruchamia się łatwo, ma to dużo sensu.”
— Jeff Sogolov, inżynier AceMQ, sesja z Lucidya, maj 2025
Lista kontrolna przed aktualizacją
- Potwierdzić bieżącą wersję RabbitMQ i ustalić wymaganą ścieżkę aktualizacji
- Sprawdzić macierz zgodności Erlanga dla wersji docelowej i pośrednich
- Włączyć wszystkie flagi funkcji w bieżącej wersji (rabbitmqctl enable_feature_flag all)
- Wykonać kopię zapasową definicji klastra (topologia, użytkownicy, uprawnienia) przez Management API
- Zweryfikować pełną aktualizację w środowisku testowym (staging), zanim dotknie się produkcji
- Potwierdzić zachowanie health checków load balancera przy wyłączonych węzłach
- Przetestować w środowisku testowym ponowne łączenie klientów przy symulowanych restartach węzłów
- Zaplanować aktualizację kroczącą na okno o najniższym ruchu
- Przed rozpoczęciem mieć udokumentowany plan wycofania zmian
Szerszą ocenę gotowości przed rezerwacją okna serwisowego zawiera lista kontrolna gotowości do migracji RabbitMQ.
Zmiany w RabbitMQ 4.x, które mogą zepsuć środowisko 3.x
Większość nieudanych aktualizacji z 3.x do 4.x potyka się na jednej z kilku zmian. Żadna z nich nie jest zaskoczeniem dla kogoś, kto przeczytał informacje o wydaniu 4.0, ale każdą łatwo przeoczyć w dużym środowisku, które wyrosło na konwencjach z 3.8 i 3.9.
- Mirroring kolejek klasycznych zniknął. Lustrzane kolejki klasyczne (klucze polityk
ha-modeiha-params) oznaczono jako wycofywane w 3.9 i usunięto w 4.0. Węzeł 4.x nie tworzy kopii lustrzanych kolejek klasycznych, więc każda kolejka, która polegała na polityce HA w zakresie replikacji, staje się kolejką jednowęzłową w chwili, gdy polityka przestaje obowiązywać. To jedyna zmiana, którą trzeba obsłużyć przed aktualizacją, a nie po niej: każdą lustrzaną kolejkę należy zmigrować do kolejki kworum, a następnie usunąć polityki HA.rabbitmq-diagnostics check_if_cluster_has_classic_queue_mirroring_policypokazuje, czy jakieś jeszcze pozostały. Kompromisy opisujemy w artykule kolejki klasyczne a kolejki kworum. - Przejściowe kolejki niewyłączne są wycofywane. Nietrwałe kolejki, które nie są wyłączne dla połączenia, są oznaczone jako funkcja wycofywana (deprecated) i mogą zostać zablokowane w konfiguracji. W 4.x nadal działają, ale należy planować deklarowanie wszędzie kolejek trwałych, a kolejek wyłącznych używać dla stanu naprawdę związanego z pojedynczym połączeniem.
- Domyślny typ kolejki. Zadeklarowanie kolejki bez
x-queue-typenadal tworzy kolejkę klasyczną, chyba że virtual host ustawiadefault_queue_type. Dla nowych obciążeń należy ustawić go naquorumdla każdego vhosta i upewnić się, że kod klienta deklarujący kolejki przekazuje jawniex-queue-type, aby nikogo nie zaskoczyła wartość domyślna na poziomie vhosta. - AMQP 1.0 jest protokołem podstawowym. W 4.0 osobna wtyczka AMQP 1.0 nie jest już potrzebna; 1.0 jest zaimplementowany natywnie obok 0-9-1 na tym samym listenerze. Nie ma to wpływu na istniejące klienty 0-9-1. Zespoły, które korzystały ze starej wtyczki, powinny usunąć ją z listy włączonych wtyczek, a te, które chcą używać 1.0, powinny przejść na utrzymywane biblioteki klienckie 1.0 zamiast starszych.
- Khepri jako magazyn metadanych. Khepri, oparty na Raft następca Mnesia, pojawił się jako funkcja eksperymentalna w 3.13 i jest wspierany w 4.x, ale wymaga świadomego włączenia. Po aktualizacji węzły nadal korzystają z Mnesia, dopóki celowo nie włączy się flagi funkcji
khepri_db. Należy to traktować jako odrębną zmianę z własnym oknem testowym, a nie efekt uboczny zmiany wersji. - Najpierw trzeba włączyć wszystkie flagi funkcji. Klaster 3.13 z choćby jedną wyłączoną stabilną flagą funkcji nie może przyjąć węzła 4.x, a węzeł 4.x odmówi uruchomienia w takim klastrze. Wszystko należy włączyć, zanim zostanie zaktualizowany pierwszy węzeł.
- Wtyczki i interfejs zarządzania. Wtyczki skompilowane dla 3.x wymagają kompilacji dla 4.x. Sama wtyczka zarządzania przechodzi do nowej wersji, ale traci widoki mirroringu, a wtyczka AMQP 1.0 przestaje cokolwiek robić. Każdą wtyczkę społecznościową należy sprawdzić, zanim założy się, że działa.
- MQTT 5. Obsługa MQTT 5 pojawiła się w 3.13 i przechodzi do 4.x. Jeśli środowisko przechodzi z 3.12 lub starszej wersji, klienty MQTT zyskują ją po drodze.
- Erlang. 4.x wymaga Erlang/OTP 26 lub nowszego. Jeśli węzły nadal działają na OTP 25, aktualizacja Erlanga odbywa się w ramach aktualizacji kroczącej, węzeł po węźle. Przed wyborem wersji docelowej warto zapoznać się z naszą notatką o końcu wsparcia Erlang 26 a RabbitMQ.
Pozostać przy 3.13 czy aktualizować do 4.x?
3.13 to ostatnia seria 3.x. Okno wsparcia społeczności dla niej jest krótkie, a po jego zamknięciu nie będzie już poprawek bezpieczeństwa upstream dla żadnej wersji 3.x. To właśnie to rzeczywiste ograniczenie przesądza o decyzji.
Pozostanie przy 3.13 jest rozsądne dokładnie w jednym przypadku: gdy mają Państwo komercyjną lub rozszerzoną umowę wsparcia, która przenosi poprawki bezpieczeństwa do używanej wersji. Bez niej klaster 3.13 to tykający zegar podatności CVE. Nasze rozszerzone wsparcie LTS obejmuje wersje od 3.8.x do 3.13.x z przenoszonymi poprawkami, dzięki czemu klienci mogą korzystać ze starszych serii według harmonogramu, nad którym mają kontrolę, a nie według kalendarza upstream. To pozwala zyskać czas, ale nie zwalnia z planowania przejścia.
Aktualizację należy przeprowadzić, gdy spełnione są wszystkie cztery warunki:
- Lustrzane kolejki klasyczne zniknęły i nie pozostały żadne polityki HA.
- Każda stabilna flaga funkcji jest włączona na każdym węźle.
- Erlang działa na OTP 26 lub nowszym albo są Państwo gotowi zaktualizować go w trakcie aktualizacji kroczącej.
- Aplikacje klienckie korzystają z utrzymywanych wersji bibliotek, które poprawnie współpracują z kolejkami kworum (prawidłowa obsługa
x-delivery-limit, dead-letteringu i ponownego łączenia).
Warto przeprowadzić aktualizację wcześniej, niż wynikałoby z kalendarza serwisowego, jeśli potrzebny jest AMQP 1.0 bez wtyczki, MQTT 5 na starszej wersji 3.x lub ulepszenia kolejek kworum z 4.x, w tym priorytety komunikatów i domyślny limit dostarczeń, który zapobiega bezustannemu krążeniu „zatrutych” komunikatów (poison messages).
W przypadku wersji od 3.8 do 3.12 odpowiedź jest taka sama, ale ścieżka dłuższa: najpierw przejść na 3.13, ustabilizować środowisko, a potem przejść na 4.x. Realizujemy dla klientów oba etapy i w ten sposób określany jest zakres usługi aktualizacji i poprawek RabbitMQ.
To, czy pozostanie jest bezpieczne, to inne pytanie niż to, czy jest możliwe: artykuł czy RabbitMQ 3.x jest nadal bezpieczny omawia daty końca wsparcia i ekspozycję na podatności CVE seria po serii. Jeśli zdecydują się Państwo pozostać, rozszerzone wsparcie LTS dla RabbitMQ 3.x zapewnia aktualne poprawki, dopóki aktualizacja czeka na okno serwisowe.
Procedura aktualizacji kroczącej, którą stosujemy
Oto sekwencja, którą stosujemy w klastrach klientów. Zakłada klaster z trzema lub pięcioma węzłami, kolejki kworum dla wszystkiego, co ważne, oraz klientów, którzy ponawiają połączenie po jego utracie.
- Inwentaryzacja. Zanotować wersje, wersje Erlanga, włączone wtyczki i wszystkie polityki. Na dowolnym węźle uruchomić
rabbitmq-diagnostics check_if_any_deprecated_features_are_usedorazrabbitmq-diagnostics check_if_cluster_has_classic_queue_mirroring_policy. Oba polecenia muszą zwrócić czysty wynik, zanim przejdzie się dalej. - Włączyć wszystkie stabilne flagi funkcji.
rabbitmqctl enable_feature_flag alluruchomione na jednym węźle działa w całym klastrze. Potwierdzić za pomocąrabbitmqctl list_feature_flags; każda flaga ze statusemdisabledblokuje aktualizację. - Przekonwertować lustrzane kolejki klasyczne na kolejki kworum, przepływ po przepływie. Kolejek kworum nie da się utworzyć przez konwersję w miejscu. Dla każdego przepływu należy zadeklarować kolejkę kworum, przekierować konsumentów, przekierować producentów, opróżnić starą kolejkę i ją usunąć. Robić to osobno dla każdej aplikacji, aby ewentualny błąd dotknął jednego przepływu, a nie całego środowiska.
- Zweryfikować docelową wersję Erlanga. Potwierdzić, że pakiet OTP 26 lub nowszy jest dostępny na każdym węźle i że jest to wersja, z którą testowano używaną kompilację 4.x.
- Wyeksportować definicje i wykonać kopię zapasową.
rabbitmqctl export_definitionsoraz kopia zapasowa katalogu danych na poziomie systemu plików na każdym węźle. Eksport definicji jest podstawą odbudowy, jeśli granica wycofania zostanie przekroczona. - Aktualizować po jednym węźle. Przed zatrzymaniem węzła uruchomić
rabbitmq-upgrade await_online_quorum_plus_one, aby żadna kolejka kworum nie straciła większości, gdy węzeł będzie niedostępny. Następnierabbitmq-upgrade drainprzełącza węzeł w tryb serwisowy, łagodnie zamyka połączenia klientów i przenosi przywództwo kolejek kworum na inne węzły. Zatrzymać usługę, w razie potrzeby zaktualizować Erlanga, zaktualizować RabbitMQ, uruchomić usługę i potwierdzić, że węzeł ponownie dołączył do klastra. - Poczekać, aż członkowie kolejek kworum nadrobią zaległości. Uruchomić
rabbitmq-queues quorum_status <queue>dla najbardziej obciążonych kolejek lubrabbitmq-diagnostics check_if_node_is_quorum_criticalna kolejnym węźle przeznaczonym do zatrzymania. Nie przechodzić do następnego węzła, dopóki ta weryfikacja nie przejdzie pomyślnie. - Sprawdzić, czy klienty ponownie się połączyły. Liczba połączeń w interfejsie zarządzania powinna na zaktualizowanym węźle wrócić do poziomu wyjściowego. Jeśli biblioteka kliencka nie ponawia połączenia, należy to naprawić teraz, przed kolejnym węzłem.
- Powtórzyć dla każdego pozostałego węzła. W tym oknie klaster działa na mieszanych wersjach 3.13 i 4.x. Do czasu zaktualizowania ostatniego węzła nie należy zmieniać polityk, dodawać kolejek ani włączać niczego nowego.
- Włączyć nowe flagi funkcji 4.x. Po zaktualizowaniu ostatniego węzła ponownie uruchomić
rabbitmqctl enable_feature_flag all. To granica wycofania: po włączeniu flagi funkcji dostępnej wyłącznie w 4.x nie ma ścieżki powrotu do starszej wersji. Wszystko przed tym krokiem można odwrócić, przywracając węzeł do 3.13.
rabbitmqctl enable_feature_flag all
rabbitmq-upgrade await_online_quorum_plus_one
rabbitmq-upgrade drainBlue-green to alternatywa, gdy klaster jest na tyle mały, że można go odbudować, eksport definicji jest wiarygodny, a klienty można przenieść za pomocą DNS lub load balancera. Daje czysty klaster 4.x i nienaruszony klaster 3.13, do którego można wrócić. Preferujemy to podejście w klastrach, które przez lata zgromadziły nieudokumentowane polityki.
W obu przypadkach wsparcie techniczne obejmuje okno aktualizacji z czasem reakcji 15 minut dla zgłoszeń P1, co ma największe znaczenie między krokiem 6 a krokiem 10.
FAQ
Czy można zaktualizować RabbitMQ 3.13 bezpośrednio do 4.x?
Tak. Aktualizacja krocząca z 3.13.x do 4.0.x jest wspierana, pod warunkiem że wszystkie stabilne flagi funkcji (feature flags) są włączone, nie pozostały żadne polityki mirroringu kolejek klasycznych, a Erlang jest w wersji OTP 26 lub nowszej. Z wersji 3.12 lub starszej nie da się przeskoczyć do 4.x; najpierw trzeba zaktualizować do 3.13, włączyć jej flagi funkcji i dopiero wtedy kontynuować. Powodem jest to, że węzły 4.x dołączają wyłącznie do klastrów, w których w pełni włączony jest zestaw flag funkcji 3.13, a starsze serie nie mogą spełnić tego warunku.
Czy można pozostać przy RabbitMQ 3.x?
Można, ale bezpiecznie tylko w ramach umowy wsparcia, która przenosi (backportuje) poprawki bezpieczeństwa, ponieważ poprawki upstream dla 3.x kończą się wraz z oknem wsparcia społeczności dla 3.13. Nasze rozszerzone wsparcie LTS obejmuje wersje od 3.8.x do 3.13.x z przenoszonymi poprawkami podatności CVE właśnie na taką sytuację. Pozostanie przy 3.x ma sens, gdy migracja klientów, zamrożenie zmian ze względów zgodności lub konwersja kolejek wymagają więcej czasu, niż pozwala kalendarz upstream. Nie ma sensu jako stan trwały; przejście na 4.x należy zaplanować według własnego harmonogramu.
Jak zaktualizować RabbitMQ bez przestojów?
Aktualizacją kroczącą, węzeł po węźle. Należy włączyć wszystkie flagi funkcji, usunąć lustrzane kolejki klasyczne, wyeksportować definicje, a następnie dla każdego węzła uruchomić rabbitmq-upgrade await_online_quorum_plus_one, opróżnić go (drain), zaktualizować Erlanga i RabbitMQ, uruchomić ponownie i poczekać, aż członkowie kolejek kworum nadrobią zaległości, zanim przejdzie się do kolejnego węzła. Klienty, które ponawiają połączenie po jego utracie, odnotują krótkie ponowne połączenie, a nie przestój. Model blue-green, z nowym klastrem 4.x i przełączeniem klientów, to opcja na wypadek, gdy istniejący klaster jest zbyt zagmatwany, by aktualizować go w miejscu.
Czy RabbitMQ 4 wymaga Erlang 26?
Tak. RabbitMQ 4.x wymaga Erlang/OTP 26 lub nowszego. Jeśli węzły 3.13 działają już na OTP 26, krok dotyczący Erlanga niczego nie zmienia; jeśli działają na OTP 25, należy zaktualizować Erlanga na każdym węźle w tym samym oknie aktualizacji kroczącej co pakiet RabbitMQ. Warto sprawdzić tabelę zgodności dla konkretnego wydania poprawkowego 4.x, które ma zostać zainstalowane, ponieważ późniejsze wydania 4.x podnoszą minimalną wersję. Nasz artykuł o końcu wsparcia Erlang 26 wyjaśnia, co to oznacza dla harmonogramów wsparcia.