Leitfaden · RabbitMQ

RabbitMQ 3.x auf 4.x: Upgrade-Runbook

Die unterstützte Hop-Abfolge bis RabbitMQ 4.4, die Go/No-Go-Gates, die vor dem Wartungsfenster erfüllt sein müssen, der Ablauf pro Knoten innerhalb des Fensters und was sich in jeder Phase rückgängig machen lässt und was nicht. Abgeglichen mit rabbitmq.com am 29. Oktober 2026, zusammen mit den Release Notes zu 4.x.

Scott Sternloff

Von Scott Sternloff, Senior Enterprise Architect

LinkedIn · Aktualisiert am · 11 Min. Lesezeit · 8 Abschnitte

Auf dieser Seite

Zwei Hops ab 3.13, nach Aktivierung der Flags nur noch vorwärts

Zwei Hops ab 3.13, nach Aktivierung der Flags nur noch vorwärts

Aktuell ist 4.4.0, und Rolling Upgrades auf 4.4 werden nur ab 4.2.x oder 4.3.x unterstützt. Cluster mit 3.13, 4.0 und 4.1 gehen daher zuerst auf 4.2.x, und 3.12 oder älter erreicht vorher 3.13. Für einen 3.13-Cluster mit aktiviertem Khepri gibt es überhaupt keinen In-place-Pfad: Er braucht eine Blue-Green-Deployment-Migration.

  • Vor dem Wartungsfenster: alle stabilen Feature Flags aktiviert, kein Classic Queue Mirroring mehr im Einsatz, khepri_db vor dem Verlassen von 4.2 aktiviert, eine Erlang-Version, die beide Enden jedes Hops unterstützen.
  • Im Wartungsfenster: immer nur ein Knoten; zuerst gedraint und per Health Check geprüft, bevor der nächste Knoten gestoppt wird.
  • Rollback: Downgrades werden nicht unterstützt, und ein einmal aktiviertes Feature Flag lässt sich nicht deaktivieren. Der einzige dokumentierte Weg zurück ist Blue-Green-Deployment, also das Zurückschalten der Anwendungen auf den alten Cluster.

Wofür dieses Runbook gedacht ist

Dies ist die Checkliste, die Sie am Upgrade-Tag abarbeiten: Hops, Gates, Befehle und eine Rollback-Tabelle, in der richtigen Reihenfolge. Die ausführliche Erklärung, warum sich ein Upgrade von 3 auf 4 ohne Downtime durchführen lässt, finden Sie im Upgrade-Artikel; für Migrationen zwischen Brokern oder eine komplette Umstellung von Classic auf Quorum Queues lesen Sie den Migrationsleitfaden. Diese Seite verlinkt auf beide, statt sie zu wiederholen.

Prüfen, ob der Hop ein unterstütztes Rolling Upgrade ist

Nur die folgenden Hops werden als Rolling Upgrades unterstützt. Planen Sie die Route daher vor allem anderen. Patch-zu-Patch-Upgrades innerhalb einer Serie werden ebenfalls unterstützt. Zwei Versionen, zwischen denen kein Rolling Upgrade möglich ist, können auch nicht gemeinsam in einem Cluster laufen.

Unterstützte Upgrade-Pfade für RabbitMQ Rolling Upgrades (Upgrade-Leitfaden auf rabbitmq.com, Doku 4.4, geprüft am 29. Oktober 2026)
VonNachRolling Upgrade?Hinweise
4.3.x4.4.xUnterstütztBeide laufen auf Erlang 27. Wechseln Sie nach Erreichen von 4.4.0 auf Erlang 28 oder 29.
4.2.x4.4.xUnterstütztDie kürzeste Route ab 4.2. Ab 4.2.9 ist Erlang 27 erforderlich.
4.2.x4.3.xUnterstütztDie einzige Route zu 4.3; laut Release Notes zu 4.3.0 ist zuvor der neueste 4.2.x-Patch Pflicht.
4.1.x4.2.xUnterstütztDanach 4.2.x auf 4.4.x.
4.0.x4.2.x oder 4.1.xUnterstütztAuf 4.2.x wechseln, dann 4.2.x auf 4.4.x.
3.13.x4.2.x, 4.1.x oder 4.0.xUnterstütztNutzen Sie 4.2.x. 3.13 läuft auf Erlang 26, landen Sie daher auf einem 4.2-Patch, der auch Erlang 26.2 unterstützt.
3.13.x, 4.0.x, 4.1.x4.3.x oder 4.4.xNicht unterstütztZuerst auf 4.2.x upgraden.
3.13.x mit aktiviertem KhepriJede 4.xNicht unterstütztKhepri war in 3.13 experimentell und ist mit 4.x inkompatibel. Nutzen Sie ein Blue-Green-Deployment.
3.12.x3.13.xUnterstütztVon 3.12 auf 4.x gibt es keinen Rolling-Pfad; die Release Notes zu 4.0 bieten Blue-Green-Deployment ab 3.12.14 an.
3.11.18 bis 3.7.18Eine Serie höherUnterstützt3.11.18 auf 3.12, 3.10 auf 3.11, 3.9 auf 3.10, 3.8 auf 3.9, 3.7.18 auf 3.8: jeweils eine Serie nach der anderen.
Tabelle · Unterstützte Upgrade-Pfade für RabbitMQ Rolling Upgrades (Upgrade-Leitfaden auf rabbitmq.com, Doku 4.4, geprüft am 29. Oktober 2026). Auf kleinen Bildschirmen seitlich scrollen.

Die Route ab 3.13 so planen, dass Erlang nie ein Rolling Upgrade blockiert

Ordnen Sie die Schritte so, dass jeder Knoten stets eine Erlang-Version ausführt, die sowohl die verlassene als auch die neue RabbitMQ-Version unterstützt. So planen wir 3.13-Upgrades, und so bleibt jeder Schritt ein Rolling Upgrade. Die Doku empfiehlt, Erlang zusammen mit RabbitMQ zu aktualisieren, wo ein einzelner Schritt das erlaubt.

  1. 3.13.x auf Erlang 26.2. Wechseln Sie auf den neuesten für Sie verfügbaren 3.13.x-Patch und aktivieren Sie alle stabilen Feature Flags; laut Release Notes zu 4.0 müssen vor dem Verlassen von 3.x alle 3.13-Flags aktiv sein.
  2. Rolling Upgrade auf einen 4.2-Patch mit Erlang-26.2-Unterstützung (4.2.0 bis 4.2.8). 3.13 reicht maximal bis Erlang 26.2.x, und ab 4.2.9 ist Erlang 27 nötig. Erst dieser Zwischen-Patch ermöglicht beiden Versionen eine gemeinsame Runtime.
  3. Rolling Upgrade von Erlang 26.2 auf 27.x unter 4.2. 4.2.0 bis 4.2.8 unterstützen 26.2 bis 27.x, auch dies ist also eine Rolling-Änderung.
  4. Rolling Upgrade auf den neuesten 4.2.x-Patch, dann alle stabilen Flags aktivieren, einschließlich khepri_db. Ab 4.3 ist Khepri der einzige Metadata Store, Mnesia entfällt, und die Release Notes zu 4.3.0 führen khepri_db als Pflicht auf.
  5. 4.2 stabil laufen lassen, dann Rolling Upgrade von 4.2.x auf 4.4.0 unter Erlang 27. Anschließend die 4.4-Feature-Flags aktivieren. Wir führen die beiden Hops nicht direkt nacheinander aus; 4.4.0 hat zudem einen Fehler behoben, der ein 3.13-auf-4.2-Upgrade mit unmittelbar folgendem Wechsel auf 4.3 scheitern lassen konnte.
  6. Optional: Rolling Upgrade von Erlang auf 28 oder 29. 4.4.0 unterstützt beide vollständig für Rolling Upgrades. Nicht unter 4.2 oder 4.3 vor 4.3.6: Dort erlaubt die Doku Erlang 28 nur für neue Cluster, weil Khepri-Cluster beim Wechsel von 27 auf 28 auf ein bekanntes Mixed-Version-Problem stoßen können.

Hat der 3.13-Cluster AMQP-1.0-Clients über das alte Plugin rabbitmq_amqp1_0 bedient, verlangen die Release Notes zu 4.3.0 mindestens ein Rolling Update nach Aktivierung des Flags rabbitmq_4.0.0 und vor dem Upgrade auf 4.3.0; dieselbe Regel wenden wir vor 4.4 an.

Die Go/No-Go-Gates vor dem Wartungsfenster erfüllen

Jedes der folgenden Gates muss Tage vor dem Wartungsfenster bestanden sein, denn die meisten lassen sich darin nicht mehr beheben. Führen Sie jede Prüfung auf der Version aus, die Sie verlassen.

  1. Alle stabilen Feature Flags aktiviert. Laut Upgrade-Leitfaden kann ein Upgrade sonst fehlschlagen, und ein einmal aktiviertes Flag lässt sich nicht deaktivieren. Diese Entscheidung treffen Sie also in Ruhe und nicht um 2 Uhr nachts. rabbitmqctl list_feature_flags, dann rabbitmqctl enable_feature_flag all.
  2. Keine abgekündigten Features im Einsatz. rabbitmq-diagnostics check_if_any_deprecated_features_are_used endet mit einem Exit-Code ungleich null, wenn welche genutzt werden. Der Befehl erkennt Classic Queue Mirroring, aber kein globales QoS; prüfen Sie den Client-Code darauf separat.
  3. Kein Classic Queue Mirroring mehr. Mirroring wurde in 4.0 entfernt, und Mirroring-Keys in Policies bleiben einfach wirkungslos. Eine Mirrored Queue wird so ohne Fehlermeldung zur Classic Queue mit nur einem Replikat. Migrieren Sie Queues, die Replikation benötigen, auf Quorum Queues und entfernen Sie dann die ha-Keys aus jeder Policy in jedem vhost (rabbitmqctl list_policies --vhost <vhost>). Übrig gebliebene ha-mode-Policies gehörten zu den Befunden eines 3.13.7-auf-4.2-Upgrades, zu dessen Wiederherstellung wir gerufen wurden.
  4. Khepri war unter 3.13 nicht aktiviert. Prüfen Sie khepri_db in rabbitmqctl list_feature_flags. Ist es unter 3.13 aktiviert, stoppen Sie: Es gibt keinen In-place-Pfad, nur Blue-Green-Deployment.
  5. Anwendungen kommen mit den 4.3-Defaults zurecht. Ab 4.3.0 sind transiente, nicht exklusive Queues, globales QoS und queue_master_locator standardmäßig verboten, und das Deklarieren einer Queue mit x-queue-mode oder x-queue-version=1 schlägt fehl, weil CQv1 entfernt wurde. Braucht eine Anwendung wirklich transiente, nicht exklusive Queues, setzen Sie vor dem Upgrade deprecated_features.permit.transient_nonexcl_queues = true auf jedem Knoten und starten Sie die Knoten neu.
  6. Partition-Handling-Keys entfernt. Ab 4.3 werden die cluster_partition_handling-Keys akzeptiert, bleiben aber wirkungslos, und mit Khepri muss eine Mehrheit der Knoten online sein, damit der Cluster verfügbar ist. Entfernen Sie die Keys, damit niemand sie für einen Schutz hält.
  7. Ein Erlang-Plan für jeden Hop. Jeder Knoten muss eine Erlang-Version ausführen, die beide Versionen des Hops unterstützen; siehe Schritt 2 und die Matrix.
  8. Der Cluster ist gesund und verkraftet einen fehlenden Knoten. Keine Alarme (rabbitmq-diagnostics check_alarms), keine laufende Replikat-Synchronisierung von Queues oder Streams, und rabbitmq-diagnostics check_if_node_is_quorum_critical besteht auf jedem Knoten. Verbindungen und Queue Leader wandern auf die verbleibenden Knoten, solange einer down ist; dimensionieren Sie entsprechend.
  9. Backups außerhalb des Knotens. Die Doku rät dringend zum Backup des Datenverzeichnisses jedes Knotens, und eine exportierte Definitionsdatei macht aus einem Neuaufbau eine Sache von Minuten: rabbitmqctl export_definitions /path/off-node/definitions.json.
  10. Clients verbinden sich selbstständig neu. Ein gestoppter Knoten schließt seine Client-Verbindungen; Anwendungen brauchen automatische Recovery und entweder einen Load Balancer oder eine Host-Liste.
  11. Breaking Changes von 4.4 geprüft. OpenID Connect Discovery wird strenger validiert (betrifft bekanntermaßen Cloud Foundry UAA), GET /api/auth/hash_password wurde zu POST, und die von Knoten mit 3.13 und älter geschriebenen x-amqp-1.0-*-Header werden nicht mehr geparst.
  12. Baseline und Link-Inventar dokumentiert. Queue-Tiefen, Consumer-Zahlen, Verbindungen und Reserven pro Knoten sowie jeder Federation-Upstream und jede Shovel (rabbitmqctl list_parameters --vhost <vhost>). Ohne diese Daten können Sie eine Regression nicht von einem normalen Tag unterscheiden und den einen Link nicht erkennen, der nicht zurückkam.
  13. CLI-Tools passen zur Broker-Version. Nach einem Hop von 3.12.14 auf 3.13.14 haben wir erlebt, dass rabbitmq-diagnostics und rabbitmqctl fehlschlugen, weil die paketierten Tools nicht zusammen mit dem Server ersetzt wurden. Prüfen Sie sie, bevor Sie sie für eine Diagnose brauchen.

Reaktionszeitziele ab 15 Minuten, je nach Plan. Namentlich zugeordnete Senior Engineers.

Kontakt

Den Ablauf pro Knoten ausführen, immer nur ein Knoten

Upgraden Sie einen Knoten, weisen Sie seinen gesunden Zustand nach und gehen Sie erst dann zum nächsten; niemals zwei gleichzeitig. In einem Cluster mit drei Knoten müssen zwei Knoten laufen, damit Quorum Queues, Streams und Khepri ihre Mehrheit behalten.

  1. Gate: Der Knoten kann sicher gestoppt werden. rabbitmq-diagnostics check_if_node_is_quorum_critical muss bestehen. In der Automatisierung blockiert rabbitmq-upgrade await_online_quorum_plus_one, bis genügend Knoten laufen.
  2. Knoten drainen. rabbitmq-upgrade drain versetzt den Knoten in den Wartungsmodus: Er nimmt keine Verbindungen mehr an, schließt bestehende und übergibt seine Quorum-Queue-Leader an andere Knoten. Ein Knoten sollte Minuten, nicht Stunden in diesem Modus bleiben.
  3. Stoppen, upgraden, starten. RabbitMQ, seine CLI-Tools und, falls dieser Hop es vorsieht, Erlang. Ein Neustart beendet den Wartungsmodus automatisch; rabbitmq-upgrade revive ist nur für einen gedrainten Knoten gedacht, den Sie doch nicht neu starten.
  4. Gate: Der Knoten ist korrekt wieder beigetreten. rabbitmq-diagnostics check_running, rabbitmqctl cluster_status und rabbitmq-diagnostics check_alarms, dann Consumer und Queue-Tiefen mit der Baseline vergleichen. Erst weitermachen, wenn sie übereinstimmen.
  5. Für den nächsten Knoten wiederholen. Mixed-Version-Cluster sind für Rolling Upgrades vorgesehen und sollten laut Release Notes zu 4.3.0 nicht länger als einige Stunden laufen.
  6. Nach dem letzten Knoten: neue Flags aktivieren und Rebalance ausführen. rabbitmqctl enable_feature_flag all, dann rabbitmq-queues rebalance all, weil die Leader nach einem Rolling Upgrade ungleich verteilt sind. Bitten Sie Nutzer der Management-UI, Browser-Cache und Speicher für deren Domain zu leeren.

Wissen, was sich in jeder Phase rückgängig machen lässt

Die Rollback-Optionen schrumpfen mit jeder Phase, und die Doku unterstützt Downgrades überhaupt nicht: Sie sind ungetestet, und manche Patch-Releases ließen sich nicht einmal auf den vorherigen Patch zurücksetzen. Legen Sie den Abbruchpunkt fest, bevor das Wartungsfenster beginnt.

Rollback-Optionen beim RabbitMQ Upgrade nach Phase (Upgrade- und Feature-Flag-Leitfäden auf rabbitmq.com, Release Notes zu 4.4.0)
Erreichte PhaseIst ein Zurück möglich?Vorgehen
Gates erledigt, noch kein Knoten gestopptJaAbbrechen; außer den auf der alten Version aktivierten Flags hat sich nichts geändert.
Einige Knoten upgegradet, neue Flags nicht aktiviertNicht unterstütztVorwärts wiederherstellen: das Rolling Upgrade abschließen oder einen fehlgeschlagenen Knoten auf der Mehrheitsversion neu aufbauen und wieder beitreten lassen. Restore aus dem Backup des Datenverzeichnisses nur als letztes Mittel.
Feature Flags der neuen Version aktiviertNeinEin einmal aktiviertes Feature Flag lässt sich nicht deaktivieren. Nur vorwärts; der Definitions-Export ist der Weg zum Neuaufbau.
Auf 4.4 mit geschriebenen Classic-Queue-DatenNein4.4 schreibt ein neues v2-Format für den Message Store; ein Knoten mit v2-Dateien kann nicht auf 4.3.x oder älter zurückgesetzt werden.
Blue-Green-Deployment: Anwendungen umgezogen, alter Cluster läuft nochJaSchalten Sie die Anwendungen zurück auf den alten Cluster. Das ist der einzige Rollback, den die Doku beschreibt; behalten Sie den alten Cluster, bis der letzte Consumer verifiziert ist.
Tabelle · Rollback-Optionen beim RabbitMQ Upgrade nach Phase (Upgrade- und Feature-Flag-Leitfäden auf rabbitmq.com, Release Notes zu 4.4.0). Auf kleinen Bildschirmen seitlich scrollen.

Wenn etwas schiefgeht: Symptom, Ursache, Lösung

  • Ein Knoten tritt nach seinem Upgrade nicht wieder bei. Ein Knoten kann nur beitreten, wenn er jedes im Cluster aktivierte Feature Flag unterstützt. Ein während seiner Downtime aktiviertes Flag oder eine abweichende Version hält ihn also draußen. Bringen Sie seine Software auf die Mehrheitsversion und lassen Sie ihn wieder beitreten; in unseren Recoveries war es schneller und sicherer, diesen einen Knoten zurückzusetzen und die Metadaten des Clusters übernehmen zu lassen, als die vielen anderen zurückzudrehen.
  • Deklarationen schlagen nach dem Wechsel auf 4.3 oder 4.4 fehl. Transiente, nicht exklusive Queues, x-queue-mode und x-queue-version=1 werden jetzt abgelehnt, und globales QoS ist standardmäßig verboten. Passen Sie die Anwendung an oder erlauben Sie das abgekündigte Feature auf jedem Knoten.
  • Eine früher gespiegelte Queue hat mit einem Knoten ihre Messages verloren. Ihre ha-Policy war ab 4.0 wirkungslos, und sie wurde zur Classic Queue mit nur einem Replikat. Migrieren Sie sie auf eine Quorum Queue.
  • CLI-Tools funktionieren nicht mehr. Die paketierten Tools passen nicht mehr zum Broker. Installieren Sie das passende Paket neu und prüfen Sie mit rabbitmq-diagnostics status.
  • Alle Federation-Links wurden neu gestartet. Während eines Rolling Upgrades zu erwarten: Queue-Federation-Links laufen auf dem Knoten des Queue Leaders und werden nach jeder Leader Election neu erstellt. Gleichen Sie mit dem Link-Inventar ab und stellen Sie fehlende Links wieder her.
  • Durchsatz nach Migration von Mirrored Queues auf Quorum Queues gesunken. Quorum Queues persistieren jede Message vor der Bestätigung und replizieren sie. Nutzen Sie die schnellsten verfügbaren Disks und geben Sie jedem Knoten mindestens das Dreifache des effektiven WAL-Limits an Arbeitsspeicher (standardmäßig 512 MiB), bei Systemen mit hohem Durchsatz das Vierfache. Wir raten davon ab, die alten Werte durch eine geringere Replikat-Anzahl erreichen zu wollen.
  • OAuth-2-Logins schlagen nach 4.4 fehl. Der Identity Provider besteht die strengere Discovery-Validierung nicht. Setzen Sie für Provider wie Cloud Foundry UAA vor dem Upgrade auth_oauth2.discovery.verify_issuer und/oder auth_oauth2.discovery.verify_https_endpoints auf false.

Wann stattdessen ein Blue-Green-Deployment sinnvoll ist

Wählen Sie ein Blue-Green-Deployment, wenn eine der folgenden Bedingungen zutrifft. Die Doku nennt es die sicherste Strategie und empfiehlt es überall dort, wo ein Rolling Upgrade nicht möglich ist – um den Preis, eine Zeit lang zwei Cluster zu betreiben.

  • Khepri war unter 3.13 aktiviert. Es gibt keinen In-place-Pfad auf 4.x.
  • Der Cluster läuft auf 3.12 oder älter. Die Rolling-Route auf 4.4 umfasst mindestens drei Hops (3.12 auf 3.13 auf 4.2 auf 4.4), jeder mit eigenem Wartungsfenster.
  • Die IT-Landschaft ist voller Mirrored Queues. rabbitmqadmin v2 automatisiert den Wechsel von Mirrored Queues unter 3.13.x auf Quorum Queues als Blue-Green-Deployment-Migration.
  • Die Knoten laufen auf einem Betriebssystem, das Sie ohnehin ersetzen wollten.
  • Sie brauchen einen Probelauf. Ein paralleler Cluster lässt die Anwendung gegen 4.4 laufen, bevor Produktions-Traffic dorthin geht.

Der dokumentierte Ablauf: neuen Cluster bereitstellen, Metadaten synchronisieren, Federation einrichten, Consumer umziehen, Messages abarbeiten, Publisher umziehen, dann den alten Cluster stilllegen. Wo wir für eine große oder alte IT-Landschaft beide Routen kalkuliert haben, war der parallele Cluster oft unsere Empfehlung.

Häufig gestellte Fragen

Kann ich RabbitMQ 3.13 direkt auf 4.4 upgraden?

Nein. Rolling Upgrades auf 4.4 werden nur ab 4.2.x oder 4.3.x unterstützt. Ein 3.13-Cluster geht daher von 3.13.x auf 4.2.x und dann von 4.2.x auf 4.4.x. Ein 3.13-Cluster mit aktiviertem Khepri lässt sich überhaupt nicht in place upgraden und braucht ein Blue-Green-Deployment.

Kann ich ein RabbitMQ Upgrade rückgängig machen?

Nicht in place. RabbitMQ unterstützt keine Downgrades, ein einmal aktiviertes Feature Flag lässt sich nicht deaktivieren, und ein 4.4-Knoten, der sein neues Message-Store-Format für Classic Queues geschrieben hat, kann nicht auf 4.3.x zurück. Der einzige dokumentierte Rollback ist Blue-Green-Deployment: Anwendungen zurück auf den alten Cluster schalten.

Braucht ein RabbitMQ Upgrade von 3 auf 4 Downtime?

Nicht für den Broker. Ein Rolling Upgrade stoppt immer nur einen Knoten, und laut Doku müssen nicht alle Knoten gestoppt werden. Auch Erlang lässt sich rollierend aktualisieren, wenn jeder Knoten eine Version ausführt, die beide RabbitMQ-Versionen des Hops unterstützen. Deshalb landet die Route ab 3.13 auf einem 4.2-Patch, der noch Erlang 26.2 unterstützt, bevor es auf Erlang 27 geht.

Warum ist mein RabbitMQ Upgrade mittendrin fehlgeschlagen?

Die üblichen Ursachen sind ein deaktiviert gebliebenes stabiles Feature Flag, ein Knoten, der die Aktivierung eines Flags während seiner Downtime verpasst hat, oder Anwendungen, die Queues deklarieren, die 4.3 jetzt ablehnt, etwa transiente, nicht exklusive Queues oder x-queue-mode. Alle drei zeigen sich in den Pre-Flight-Gates, wenn Sie diese vor dem Wartungsfenster ausführen.

Was passiert mit Classic Mirrored Queues nach dem Upgrade auf RabbitMQ 4?

Mirroring wurde in 4.0 entfernt. Die Mirroring-Teile der Policies bleiben wirkungslos, und die Queues laufen als Classic Queues mit nur einem Replikat weiter. Sie verlieren ihre Redundanz also ohne Fehlermeldung. Migrieren Sie Queues, die Replikation benötigen, vor dem Upgrade auf Quorum Queues.

Kostenlose Beratung

Lassen Sie Experten auf Ihre RabbitMQ-Cluster-Umgebung schauen

Ob Sie einen Produktionsvorfall beheben, eine Migration planen oder eine zweite Meinung zu Ihrer Architektur wünschen – unser Team steht bereit. Kein Verkaufsgespräch, nur Antworten.

E-Mail schreiben