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.
| De | Vers | Mise à niveau progressive ? | Remarques |
|---|---|---|---|
| 4.3.x | 4.4.x | Supporté | Les deux tournent sur Erlang 27. Passez à Erlang 28 ou 29 après avoir atteint 4.4.0. |
| 4.2.x | 4.4.x | Supporté | L'itinéraire le plus court depuis 4.2. Les versions 4.2.9 et ultérieures exigent Erlang 27. |
| 4.2.x | 4.3.x | Supporté | 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.x | 4.2.x | Supporté | Puis de 4.2.x vers 4.4.x. |
| 4.0.x | 4.2.x ou 4.1.x | Supporté | Passez à 4.2.x, puis de 4.2.x vers 4.4.x. |
| 3.13.x | 4.2.x, 4.1.x ou 4.0.x | Supporté | 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.x | 4.3.x ou 4.4.x | Non supporté | Mettez d'abord à niveau vers 4.2.x. |
| 3.13.x avec Khepri activé | Toute version 4.x | Non supporté | Khepri en 3.13 était expérimental et incompatible avec 4.x. Utilisez un déploiement blue-green. |
| 3.12.x | 3.13.x | Supporté | 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.18 | Une série au-dessus | Supporté | 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. |
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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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_flagspuisrabbitmqctl enable_feature_flag all. - Aucune fonctionnalité obsolète en usage.
rabbitmq-diagnostics check_if_any_deprecated_features_are_usedrenvoie 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. - 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. - Khepri n'a pas été activé sur 3.13. Vérifiez
khepri_dbdansrabbitmqctl list_feature_flags. S'il est activé sur 3.13, arrêtez-vous : aucun chemin sur place, seulement le blue-green. - 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-modeoux-queue-version=1échoue car CQv1 est supprimé. Si une application a réellement besoin de files transitoires non exclusives, définissezdeprecated_features.permit.transient_nonexcl_queues = truesur chaque nœud, et redémarrez-les, avant la mise à niveau. - Clés de gestion des partitions réseau supprimées. À partir de 4.3, les clés
cluster_partition_handlingsont 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. - 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.
- 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, etrabbitmq-diagnostics check_if_node_is_quorum_criticalvalidé 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. - 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. - 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.
- 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_passwordest devenu un POST, et les en-têtesx-amqp-1.0-*écrits par les nœuds 3.13 et antérieurs ne sont plus analysés. - 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. - 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.
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é.
- Contrôle : le nœud peut être arrêté sans risque.
rabbitmq-diagnostics check_if_node_is_quorum_criticaldoit être validé. En automatisation,rabbitmq-upgrade await_online_quorum_plus_onebloque jusqu'à ce que suffisamment de nœuds soient actifs. - Drainez-le.
rabbitmq-upgrade drainplace 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. - 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 revivene sert que pour un nœud drainé que vous avez décidé de ne pas redémarrer. - Contrôle : il a correctement rejoint le cluster.
rabbitmq-diagnostics check_running,rabbitmqctl cluster_statusetrabbitmq-diagnostics check_alarms, puis comparez consommateurs et profondeurs de files avec la référence. Ne poursuivez que s'ils concordent. - 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.
- Après le dernier nœud : activez les nouveaux flags et lancez le rééquilibrage.
rabbitmqctl enable_feature_flag all, puisrabbitmq-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.
| Étape atteinte | Retour possible ? | Que faire |
|---|---|---|
| Contrôles validés, aucun nœud arrêté | Oui | Abandonnez ; rien n'a changé hormis les flags activés sur l'ancienne version. |
| Certains nœuds mis à niveau, nouveaux flags non activés | Non 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és | Non | Un 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 écrites | Non | La 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 actif | Oui | Rebasculez 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. |
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-modeetx-queue-version=1sont 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_issueret/ouauth_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.