Guide · RabbitMQ

Runbook de mise à niveau RabbitMQ 3.x vers 4.x

La séquence d'étapes supportée jusqu'à RabbitMQ 4.4, les contrôles go/no-go à valider avant la fenêtre, la séquence par nœud pendant celle-ci, et ce que vous pouvez ou non annuler à chaque étape. Vérifié sur rabbitmq.com le 29 octobre 2026, avec les notes de version 4.x.

Scott Sternloff

Par Scott Sternloff, Architecte d’entreprise senior

LinkedIn · Mis à jour le · Lecture : 13 min · 8 sections

Sur cette page

Deux étapes depuis 3.13, sans retour possible une fois les flags activés

Deux étapes depuis 3.13, sans retour possible une fois les flags activés

La 4.4.0 est la version actuelle, et les mises à niveau progressives (rolling upgrade) vers 4.4 ne sont supportées qu'à partir de 4.2.x ou 4.3.x. Les clusters 3.13, 4.0 et 4.1 passent donc d'abord par 4.2.x, et les versions 3.12 ou antérieures doivent atteindre 3.13 au préalable. Un cluster 3.13 avec Khepri activé n'a aucun chemin sur place : il exige une migration blue-green.

  • Avant la fenêtre : tous les feature flags stables activés, aucune mise en miroir de file classique en usage, khepri_db activé avant de quitter 4.2, une version d'Erlang supportée aux deux extrémités de chaque étape.
  • Pendant la fenêtre : un nœud à la fois, drainé d'abord, contrôlé avant l'arrêt du suivant.
  • Retour arrière : les rétrogradations ne sont pas supportées, et un feature flag ne peut plus être désactivé une fois activé. Le seul retour documenté est le blue-green, en rebasculant les applications vers l'ancien cluster.

À quoi sert ce runbook

C'est la checklist à dérouler le jour J : étapes, contrôles, commandes et tableau de retour arrière, dans l'ordre. Pour l'explication détaillée de la façon de mener une mise à niveau de 3 vers 4 sans interruption de service, lisez l'article sur la mise à niveau ; pour les migrations entre brokers ou un passage massif des files classiques aux quorum queues, lisez le guide de migration. Cette page renvoie aux deux plutôt que de les répéter.

Vérifiez que l'étape est une mise à niveau progressive supportée

Seules les étapes ci-dessous sont supportées en mise à niveau progressive : planifiez donc l'itinéraire avant toute chose. Les mises à niveau de correctif à correctif au sein d'une même série sont également supportées. Deux versions entre lesquelles on ne peut pas faire de mise à niveau progressive ne peuvent pas non plus coexister dans un même cluster.

Chemins de mise à niveau progressive RabbitMQ supportés (guide de mise à niveau rabbitmq.com, docs 4.4, vérifié le 29 octobre 2026)
DeVersMise à niveau progressive ?Remarques
4.3.x4.4.xSupportéLes deux tournent sur Erlang 27. Passez à Erlang 28 ou 29 après avoir atteint 4.4.0.
4.2.x4.4.xSupportéL'itinéraire le plus court depuis 4.2. Les versions 4.2.9 et ultérieures exigent Erlang 27.
4.2.x4.3.xSupportéLe seul itinéraire vers 4.3 ; les notes de version 4.3.0 exigent d'abord le dernier correctif 4.2.x.
4.1.x4.2.xSupportéPuis de 4.2.x vers 4.4.x.
4.0.x4.2.x ou 4.1.xSupportéPassez à 4.2.x, puis de 4.2.x vers 4.4.x.
3.13.x4.2.x, 4.1.x ou 4.0.xSupportéUtilisez 4.2.x. La 3.13 tourne sur Erlang 26, visez donc un correctif 4.2 qui supporte aussi Erlang 26.2.
3.13.x, 4.0.x, 4.1.x4.3.x ou 4.4.xNon supportéMettez d'abord à niveau vers 4.2.x.
3.13.x avec Khepri activéToute version 4.xNon supportéKhepri en 3.13 était expérimental et incompatible avec 4.x. Utilisez un déploiement blue-green.
3.12.x3.13.xSupportéIl n'existe aucun chemin progressif de 3.12 vers 4.x ; les notes de version 4.0 proposent le blue-green à partir de 3.12.14.
3.11.18 à 3.7.18Une série au-dessusSupporté3.11.18 vers 3.12, 3.10 vers 3.11, 3.9 vers 3.10, 3.8 vers 3.9, 3.7.18 vers 3.8 : une série à la fois.
Tableau · Chemins de mise à niveau progressive RabbitMQ supportés (guide de mise à niveau rabbitmq.com, docs 4.4, vérifié le 29 octobre 2026). Faites défiler horizontalement sur petit écran.

Ordonnez l'itinéraire depuis 3.13 pour qu'Erlang ne bloque jamais une étape

Ordonnez les étapes pour que chaque nœud exécute toujours une version d'Erlang supportée à la fois par la version de RabbitMQ qu'il quitte et par celle qu'il rejoint. C'est ainsi que nous séquençons les mises à niveau depuis 3.13, et chaque étape reste progressive. La documentation recommande de mettre à niveau Erlang en même temps que RabbitMQ lorsqu'une seule étape le permet.

  1. 3.13.x sur Erlang 26.2. Passez au dernier correctif 3.13.x disponible et activez tous les feature flags stables ; les notes de version 4.0 exigent tous les flags 3.13 avant de quitter la 3.x.
  2. Passez à un correctif 4.2 qui supporte Erlang 26.2 (4.2.0 à 4.2.8). La 3.13 plafonne à Erlang 26.2.x, et les versions 4.2.9 et ultérieures exigent Erlang 27 : ce correctif intermédiaire permet aux deux versions de partager un même runtime.
  3. Faites passer Erlang de 26.2 à 27.x sur 4.2. Les versions 4.2.0 à 4.2.8 supportent 26.2 à 27.x, ce changement est donc lui aussi progressif.
  4. Passez au dernier correctif 4.2.x, puis activez tous les flags stables, y compris khepri_db. Khepri est le seul metadata store à partir de 4.3, Mnesia a disparu, et les notes de version 4.3.0 indiquent khepri_db comme obligatoire.
  5. Laissez la 4.2 se stabiliser, puis passez de 4.2.x à 4.4.0 sur Erlang 27. Activez ensuite les feature flags 4.4. Nous n'enchaînons pas les deux étapes ; la 4.4.0 a d'ailleurs corrigé un problème pouvant faire échouer une mise à niveau de 3.13 vers 4.2 suivie immédiatement d'un passage à 4.3.
  6. Facultatif : passez Erlang en 28 ou 29. La 4.4.0 les supporte pleinement en mise à niveau progressive. Ne le faites pas sur 4.2 ni sur 4.3 avant 4.3.6 : la documentation n'y autorise Erlang 28 que pour les nouveaux clusters, car les clusters Khepri passant de 27 à 28 peuvent rencontrer un problème connu de versions mixtes.

Si le cluster 3.13 servait des clients AMQP 1.0 via l'ancien plugin rabbitmq_amqp1_0, les notes de version 4.3.0 demandent au moins une mise à jour progressive après activation du flag rabbitmq_4.0.0 et avant la mise à niveau vers 4.3.0 ; nous appliquons la même règle avant 4.4.

Validez les contrôles go/no-go avant la fenêtre

Chaque contrôle ci-dessous doit être validé plusieurs jours avant la fenêtre, car la plupart ne peuvent pas être corrigés pendant celle-ci. Exécutez chaque vérification sur la version que vous quittez.

  1. Tous les feature flags stables activés. Selon le guide de mise à niveau, la mise à niveau peut échouer sinon, et un flag ne peut plus être désactivé une fois activé : c'est une décision à prendre à tête reposée, pas à 2 h du matin. rabbitmqctl list_feature_flags puis rabbitmqctl enable_feature_flag all.
  2. Aucune fonctionnalité obsolète en usage. rabbitmq-diagnostics check_if_any_deprecated_features_are_used renvoie un code non nul si c'est le cas. La commande détecte la mise en miroir des files classiques, mais pas le QoS global : vérifiez ce point séparément dans le code client.
  3. Plus aucune mise en miroir de file classique. La mise en miroir a été supprimée en 4.0, et les clés de mise en miroir des politiques cessent simplement d'avoir le moindre effet : une file classique en miroir devient une file classique à réplica unique, sans erreur. Migrez vers des quorum queues les files qui ont besoin de réplication, puis supprimez les clés ha- de chaque politique dans chaque vhost (rabbitmqctl list_policies --vhost <vhost>). Des politiques ha-mode résiduelles figuraient parmi les constats lors d'une mise à niveau de 3.13.7 vers 4.2 que nous avons été appelés à rattraper.
  4. Khepri n'a pas été activé sur 3.13. Vérifiez khepri_db dans rabbitmqctl list_feature_flags. S'il est activé sur 3.13, arrêtez-vous : aucun chemin sur place, seulement le blue-green.
  5. Les applications supportent les valeurs par défaut de 4.3. À partir de 4.3.0, les files transitoires non exclusives, le QoS global et queue_master_locator sont refusés par défaut, et déclarer une file avec x-queue-mode ou x-queue-version=1 échoue car CQv1 est supprimé. Si une application a réellement besoin de files transitoires non exclusives, définissez deprecated_features.permit.transient_nonexcl_queues = true sur chaque nœud, et redémarrez-les, avant la mise à niveau.
  6. Clés de gestion des partitions réseau supprimées. À partir de 4.3, les clés cluster_partition_handling sont acceptées mais sans effet, et avec Khepri une majorité de nœuds doit être en ligne pour que le cluster soit disponible. Supprimez ces clés pour que personne ne les prenne pour une protection.
  7. Un plan Erlang pour chaque étape. Chaque nœud doit exécuter une version d'Erlang supportée par les deux versions de l'étape ; voir l'étape 2 et la matrice.
  8. Le cluster est sain et peut fonctionner avec un nœud en moins. Aucune alarme (rabbitmq-diagnostics check_alarms), aucune synchronisation de réplica de file ou de stream en cours, et rabbitmq-diagnostics check_if_node_is_quorum_critical validé sur chaque nœud. Les connexions et les leaders de files se déplacent vers les nœuds restants pendant qu'un nœud est arrêté : dimensionnez en conséquence.
  9. Sauvegardes stockées hors du nœud. La documentation recommande vivement de sauvegarder le répertoire de données de chaque nœud, et un fichier de définitions exporté ramène une reconstruction à quelques minutes : rabbitmqctl export_definitions /path/off-node/definitions.json.
  10. Les clients se reconnectent seuls. L'arrêt d'un nœud ferme ses connexions clientes ; les applications ont besoin d'une reprise automatique et d'un load balancer ou d'une liste d'hôtes.
  11. Changements incompatibles de 4.4 passés en revue. La découverte OpenID Connect est validée plus strictement (impact connu sur Cloud Foundry UAA), GET /api/auth/hash_password est devenu un POST, et les en-têtes x-amqp-1.0-* écrits par les nœuds 3.13 et antérieurs ne sont plus analysés.
  12. Une référence et un inventaire des liens enregistrés. Profondeurs de files, nombre de consommateurs, connexions et marge de capacité par nœud, ainsi que chaque upstream de fédération et chaque Shovel (rabbitmqctl list_parameters --vhost <vhost>). Sans cela, impossible de distinguer une régression d'une journée normale, ou de repérer le lien qui n'est pas revenu.
  13. Les outils CLI correspondent à la version du broker. Après une étape de 3.12.14 vers 3.13.14, nous avons vu rabbitmq-diagnostics et rabbitmqctl échouer parce que les outils packagés n'avaient pas été remplacés avec le serveur. Vérifiez-les avant d'en avoir besoin pour un diagnostic.

Objectifs de réponse à partir de 15 minutes, selon le plan. Ingénieurs seniors attitrés.

Nous contacter

Déroulez la séquence par nœud, un nœud à la fois

Mettez à niveau un nœud, prouvez qu'il est sain, puis passez au suivant ; jamais deux à la fois. Dans un cluster à trois nœuds, deux nœuds doivent rester actifs pour que les quorum queues, les streams et Khepri conservent une majorité.

  1. Contrôle : le nœud peut être arrêté sans risque. rabbitmq-diagnostics check_if_node_is_quorum_critical doit être validé. En automatisation, rabbitmq-upgrade await_online_quorum_plus_one bloque jusqu'à ce que suffisamment de nœuds soient actifs.
  2. Drainez-le. rabbitmq-upgrade drain place le nœud en mode maintenance : il n'accepte plus de connexions, ferme celles existantes et transfère ses leaders de quorum queues à ses pairs. Un nœud doit rester dans ce mode quelques minutes, pas des heures.
  3. Arrêtez, mettez à niveau, redémarrez. RabbitMQ, ses outils CLI et, si l'étape le prévoit, Erlang. Un redémarrage sort automatiquement le nœud du mode maintenance ; rabbitmq-upgrade revive ne sert que pour un nœud drainé que vous avez décidé de ne pas redémarrer.
  4. Contrôle : il a correctement rejoint le cluster. rabbitmq-diagnostics check_running, rabbitmqctl cluster_status et rabbitmq-diagnostics check_alarms, puis comparez consommateurs et profondeurs de files avec la référence. Ne poursuivez que s'ils concordent.
  5. Répétez pour le nœud suivant. Les clusters en versions mixtes existent pour les mises à niveau progressives et, selon les notes de version 4.3.0, ne doivent pas fonctionner plus de quelques heures.
  6. Après le dernier nœud : activez les nouveaux flags et lancez le rééquilibrage. rabbitmqctl enable_feature_flag all, puis rabbitmq-queues rebalance all, car les leaders se retrouvent inégalement répartis après la mise à niveau. Demandez aux utilisateurs de l'interface de gestion de vider le cache et le stockage du navigateur pour son domaine.

Sachez ce que vous pouvez annuler à chaque étape

Les options de retour arrière se réduisent à chaque étape, et la documentation ne supporte aucune rétrogradation : elles ne sont pas testées, et certaines versions correctives n'ont même pas pu être rétrogradées vers le correctif précédent. Fixez le point d'abandon avant l'ouverture de la fenêtre.

Options de retour arrière d'une mise à niveau RabbitMQ par étape (guides rabbitmq.com sur la mise à niveau et les feature flags, notes de version 4.4.0)
Étape atteinteRetour possible ?Que faire
Contrôles validés, aucun nœud arrêtéOuiAbandonnez ; rien n'a changé hormis les flags activés sur l'ancienne version.
Certains nœuds mis à niveau, nouveaux flags non activésNon supportéRétablissez en avançant : terminez la mise à niveau, ou reconstruisez un nœud défaillant dans la version majoritaire et réintégrez-le. Ne restaurez depuis la sauvegarde du répertoire de données qu'en dernier recours.
Feature flags de la nouvelle version activésNonUn feature flag ne peut plus être désactivé une fois activé. Uniquement vers l'avant ; l'export des définitions est la voie de reconstruction.
En 4.4 avec des données de file classique écritesNonLa 4.4 écrit un nouveau format de stockage des messages v2 ; un nœud contenant des fichiers v2 ne peut pas être rétrogradé en 4.3.x ou antérieure.
Blue-green : applications basculées, ancien cluster toujours actifOuiRebasculez les applications vers l'ancien cluster. C'est le seul retour arrière décrit par la documentation ; conservez l'ancien cluster jusqu'à vérification du dernier consommateur.
Tableau · Options de retour arrière d'une mise à niveau RabbitMQ par étape (guides rabbitmq.com sur la mise à niveau et les feature flags, notes de version 4.4.0). Faites défiler horizontalement sur petit écran.

En cas de problème : symptôme, cause, correction

  • Un nœud ne rejoint pas le cluster après sa mise à niveau. Un nœud ne peut rejoindre le cluster que s'il supporte tous les feature flags qui y sont activés : un flag activé pendant son arrêt, ou un écart de version, le maintient dehors. Alignez son logiciel sur la version majoritaire et réintégrez-le ; lors de nos interventions, réinitialiser ce seul nœud et le laisser récupérer les métadonnées du cluster s'est révélé plus rapide et plus sûr que de revenir en arrière sur tous les autres.
  • Les déclarations échouent après le passage à 4.3 ou 4.4. Les files transitoires non exclusives, x-queue-mode et x-queue-version=1 sont désormais rejetés, et le QoS global est refusé par défaut. Corrigez l'application ou autorisez la fonctionnalité obsolète sur chaque nœud.
  • Une file autrefois en miroir a perdu ses messages avec un nœud. Sa politique ha- a cessé d'agir en 4.0 et elle est devenue une file classique à réplica unique. Convertissez-la en quorum queue.
  • Les outils CLI ne fonctionnent plus. Les outils packagés ne correspondent plus au broker. Réinstallez le paquet correspondant et vérifiez avec rabbitmq-diagnostics status.
  • Tous les liens de fédération ont redémarré. Normal pendant la mise à niveau : les liens de fédération de files tournent sur le nœud du leader de la file et sont recréés après chaque élection de leader. Comparez avec l'inventaire des liens et rétablissez ceux qui manquent.
  • Le débit a chuté après le passage des files en miroir aux quorum queues. Les quorum queues persistent chaque message avant de le confirmer et le répliquent. Utilisez les disques les plus rapides disponibles, et dotez chaque nœud d'au moins trois fois la limite WAL effective en mémoire (512 MiB par défaut), quatre fois pour les systèmes à haut débit. Nous déconseillons de courir après les anciens chiffres en réduisant le nombre de réplicas.
  • Les connexions OAuth 2 échouent après 4.4. Le fournisseur d'identité ne passe pas la validation de découverte plus stricte. Pour des fournisseurs comme Cloud Foundry UAA, définissez auth_oauth2.discovery.verify_issuer et/ou auth_oauth2.discovery.verify_https_endpoints à false avant la mise à niveau.

Quand préférer le blue-green

Optez pour un déploiement blue-green dès que l'une des conditions ci-dessous est remplie. La documentation le présente comme la stratégie la plus sûre et le recommande partout où une mise à niveau progressive n'est pas possible, au prix de deux clusters à faire tourner pendant un temps.

  • Khepri a été activé sur 3.13. Aucun chemin sur place vers 4.x.
  • Le cluster est en 3.12 ou antérieure. L'itinéraire progressif vers 4.4 compte au moins trois étapes (3.12 vers 3.13 vers 4.2 vers 4.4), chacune avec sa propre fenêtre.
  • Le parc regorge de files classiques en miroir. rabbitmqadmin v2 automatise le passage des files en miroir 3.13.x aux quorum queues sous forme de migration blue-green.
  • Les nœuds tournent sur un système d'exploitation que vous comptiez remplacer de toute façon.
  • Vous avez besoin d'une répétition. Un cluster parallèle permet de faire tourner l'application sur 4.4 avant tout trafic de production.

La séquence documentée est la suivante : déployer le nouveau cluster, synchroniser les métadonnées, mettre en place la fédération, basculer les consommateurs, drainer les messages, basculer les producteurs, puis décommissionner l'ancien cluster. Lorsque nous avons chiffré les deux options pour un parc volumineux ou ancien, c'est souvent le cluster parallèle que nous avons recommandé.

Questions fréquentes

Peut-on mettre à niveau RabbitMQ 3.13 directement vers 4.4 ?

Non. Les mises à niveau progressives vers 4.4 ne sont supportées qu'à partir de 4.2.x ou 4.3.x : un cluster 3.13 passe donc de 3.13.x à 4.2.x, puis de 4.2.x à 4.4.x. Un cluster 3.13 avec Khepri activé ne peut pas du tout être mis à niveau sur place et nécessite un déploiement blue-green.

Peut-on faire un retour arrière après une mise à niveau RabbitMQ ?

Pas sur place. RabbitMQ ne supporte pas les rétrogradations, un feature flag ne peut plus être désactivé une fois activé, et un nœud 4.4 ayant écrit son nouveau format de stockage des messages de files classiques ne peut pas revenir en 4.3.x. Le seul retour arrière documenté est le blue-green : rebasculer les applications vers l'ancien cluster.

Une mise à niveau RabbitMQ 3 vers 4 impose-t-elle une interruption de service ?

Pas pour le broker. Une mise à niveau progressive arrête un nœud à la fois et la documentation précise qu'il n'est pas nécessaire d'arrêter tous les nœuds. Erlang peut évoluer de la même façon progressive si chaque nœud exécute une version supportée par les deux versions de RabbitMQ de l'étape : c'est pourquoi l'itinéraire depuis 3.13 passe par un correctif 4.2 qui supporte encore Erlang 26.2 avant de passer à Erlang 27.

Pourquoi ma mise à niveau RabbitMQ a-t-elle échoué en cours de route ?

Les causes habituelles sont un feature flag stable resté désactivé, un nœud qui a manqué l'activation d'un flag pendant son arrêt, ou des applications qui déclarent des files désormais rejetées par la 4.3, comme les files transitoires non exclusives ou x-queue-mode. Ces trois cas ressortent des contrôles préalables si vous les exécutez avant la fenêtre.

Que deviennent les files classiques en miroir après la mise à niveau vers RabbitMQ 4 ?

La mise en miroir a été supprimée en 4.0. Les paramètres de mise en miroir des politiques cessent d'avoir le moindre effet et les files continuent de fonctionner comme des files classiques à réplica unique : elles perdent leur redondance sans aucune erreur. Migrez vers des quorum queues les files qui ont besoin de réplication avant la mise à niveau.

Consultation gratuite

Un regard expert sur votre cluster RabbitMQ

Que vous deviez résoudre un incident de production, planifier une migration ou obtenir un second avis sur votre architecture, notre équipe est prête. Pas d’argumentaire commercial, seulement des réponses.

Nous écrire