En esta página
¿Por qué fallan las actualizaciones de RabbitMQ?
"Muchas veces, lo que les cuesta a las empresas, o lo que olvidan, es que no actualizan con frecuencia. A veces pasan un par de años sin hacer una actualización. Y si intentan ir de donde están directamente a la última versión, se encuentran con un montón de problemas imprevistos, porque lo que deberían haber hecho es actualizar paso a paso."
— Jeff Sogolov, ingeniero de AceMQ, sesión de trabajo con Lucidya, mayo de 2025
¿Cuál es la ruta de actualización necesaria de 3.x a 4.x?
rabbitmqctl enable_feature_flag all¿Y la compatibilidad con Erlang?
- 3.12 admite como mínimo Erlang 25.x
- 3.13 requiere como mínimo Erlang 26 (se recomienda 26.2)
- 4.x también requiere como mínimo Erlang 26.2
"Puede actualizar Erlang de 25 a 26.2 directamente. Una vez en 26.2, actualiza RabbitMQ a 3.13: ya tiene el Erlang correcto. Después, de 3.13 a 4.1, sigue sirviendo la misma versión de Erlang."
— Jeff Sogolov, ingeniero de AceMQ, sesión con Lucidya, mayo de 2025
Estrategia 1: actualización progresiva (in situ)
- Detenga el nodo 1 (solo el servicio, no el sistema operativo)
- Actualice Erlang en el nodo 1 a la versión requerida
- Actualice RabbitMQ en el nodo 1 a la versión de destino
- Inicie el servicio de RabbitMQ en el nodo 1
- Confirme que el nodo 1 volvió a unirse al clúster y está en buen estado
- Repita con los nodos 2 y 3
Estrategia 2: despliegue blue-green
- Aprovisione un nuevo clúster (green) con la versión de destino de RabbitMQ y Erlang
- Configure un upstream de colas federadas en el clúster green que apunte al clúster blue
- A medida que los consumidores pasan al clúster green, federation trae automáticamente los mensajes de blue a green
- Cuando todos los consumidores estén en green, pase los productores a green
- Una vez trasladados los productores, drene los mensajes que queden en blue con el plugin shovel
- Desmantele el clúster blue
"Blue-green no tiene tiempo de inactividad. Se puede hacer en cualquier momento, no hay modo de mantenimiento. El costo es tener dos clústeres funcionando al mismo tiempo, algo que algunas empresas no pueden permitirse, sobre todo on-premises. Pero en despliegues sobre AWS, donde se pueden levantar clústeres nuevos con facilidad, tiene mucho sentido."
— Jeff Sogolov, ingeniero de AceMQ, sesión con Lucidya, mayo de 2025
Checklist previo a la actualización
- Confirme la versión actual de RabbitMQ e identifique la ruta de actualización necesaria
- Revise la matriz de compatibilidad de Erlang para la versión de destino y las intermedias
- Habilite todos los feature flags en la versión actual (rabbitmqctl enable_feature_flag all)
- Respalde las definiciones del clúster (topología, usuarios, permisos) mediante la Management API
- Valide de principio a fin la actualización en un entorno de staging antes de tocar producción
- Confirme el comportamiento de los health checks del balanceador de carga con nodos desconectados
- Pruebe en staging el comportamiento de reconexión de los clientes simulando reinicios de nodos
- Si usa la actualización progresiva, prográmela en la ventana de menor tráfico
- Tenga documentado un plan de reversión antes de empezar
Para una visión más amplia de la preparación antes de comprometerse con una ventana, consulte la lista de verificación de preparación para la migración de RabbitMQ.
Qué cambia en RabbitMQ 4.x que puede romper un entorno 3.x
La mayoría de las actualizaciones de 3.x a 4.x que salen mal fallan por uno de unos pocos cambios. Ninguno es una sorpresa si se leen las notas de la versión 4.0, pero cada uno es fácil de pasar por alto en un entorno grande que creció con las convenciones de 3.8 y 3.9.
- La réplica de colas clásicas ya no existe. Las colas clásicas replicadas (las claves de política
ha-modeyha-params) quedaron obsoletas en 3.9 y se eliminaron en 4.0. Un nodo 4.x no replica colas clásicas, así que cualquier cola que dependía de una política de alta disponibilidad para replicarse se convierte en una cola de un solo nodo en el momento en que la política deja de aplicarse. Es el único cambio que debe resolverse antes de la actualización y no después: migre cada cola replicada a una cola de quórum y luego elimine las políticas de alta disponibilidad.rabbitmq-diagnostics check_if_cluster_has_classic_queue_mirroring_policyle indica si queda alguna. Explicamos las ventajas y desventajas en nuestro artículo sobre colas clásicas frente a colas de quórum. - Las colas transitorias no exclusivas quedan obsoletas. Las colas no durables que no son exclusivas de una conexión se marcan como funcionalidad obsoleta y pueden bloquearse por configuración. Siguen funcionando en 4.x, pero planifique declarar colas durables en todos lados y usar colas exclusivas para el estado que realmente es propio de cada conexión.
- El tipo de cola predeterminado. Declarar una cola sin
x-queue-typesigue dando una cola clásica, salvo que el virtual host definadefault_queue_type. Configúrelo enquorumpor vhost para las cargas de trabajo nuevas, y asegúrese de que el código cliente que declara colas pase unx-queue-typeexplícito para que nadie se sorprenda con un valor predeterminado a nivel de vhost. - AMQP 1.0 es un protocolo central. En 4.0 ya no se necesita el plugin aparte de AMQP 1.0; 1.0 se implementa de forma nativa junto con 0-9-1 en el mismo listener. Los clientes 0-9-1 existentes no se ven afectados. Los equipos que usaban el plugin anterior deberían quitarlo de su lista de plugins habilitados, y los que quieran usar 1.0 deberían pasar a las bibliotecas cliente de 1.0 con mantenimiento en lugar de las heredadas.
- Khepri como almacén de metadatos. Khepri, el reemplazo de Mnesia basado en Raft, salió como experimental en 3.13 y tiene soporte en 4.x, pero hay que activarlo explícitamente. Los nodos siguen usando Mnesia después de la actualización hasta que usted habilite deliberadamente el feature flag
khepri_db. Trátelo como un cambio aparte con su propia ventana de pruebas, no como un efecto secundario del cambio de versión. - Primero hay que habilitar todos los feature flags. Un clúster 3.13 con algún feature flag estable todavía deshabilitado no puede unirse a un nodo 4.x, y el nodo 4.x se niega a iniciar contra él. Habilite todo antes de que se mueva el primer nodo.
- Plugins e interfaz de administración. Los plugins compilados para 3.x necesitan versiones para 4.x. El plugin de administración se mantiene, pero pierde las vistas de réplica y el plugin de AMQP 1.0 deja de tener efecto. Audite cualquier plugin de la comunidad antes de dar por hecho que funciona.
- MQTT 5. El soporte de MQTT 5 llegó en 3.13 y se mantiene en 4.x. Si viene de 3.12 o de una versión anterior, sus clientes MQTT lo obtienen como parte de la ruta.
- Erlang. 4.x requiere Erlang/OTP 26 o posterior. Si sus nodos todavía están en OTP 25, la actualización de Erlang se hace como parte de la actualización progresiva, nodo por nodo. Consulte nuestra nota sobre el fin de vida útil de Erlang 26 y RabbitMQ antes de elegir un destino.
¿Conviene quedarse en 3.13 o actualizar a 4.x?
3.13 es la última serie 3.x. Su ventana de soporte de la comunidad es corta, y cuando se cierre no habrá parches de seguridad upstream para ninguna versión 3.x. Esa es la restricción real que determina la decisión.
Quedarse en 3.13 es razonable en un solo caso: cuando tiene un acuerdo de soporte comercial o extendido que aplica backports de las correcciones de seguridad a la versión que ejecuta. Sin eso, un clúster 3.13 es una cuenta regresiva de CVE. Nuestro soporte LTS extendido cubre de 3.8.x a 3.13.x con backports de parches, lo que permite a los clientes ejecutar series antiguas con un cronograma que ellos controlan y no uno dictado por el calendario upstream. Le da tiempo, pero no elimina la necesidad de planificar el cambio.
Actualice cuando se cumplan estas cuatro condiciones:
- Ya no hay colas clásicas replicadas ni queda ninguna política de alta disponibilidad.
- Todos los feature flags estables están habilitados en todos los nodos.
- Erlang está en OTP 26 o posterior, o está listo para actualizarlo durante la actualización progresiva.
- Las aplicaciones cliente usan versiones de bibliotecas con mantenimiento que se comportan correctamente con las colas de quórum (manejo correcto de
x-delivery-limit, del dead-lettering y de la reconexión).
Actualice antes de lo que sugiere su calendario de mantenimiento si necesita AMQP 1.0 sin el plugin, MQTT 5 en una versión 3.x anterior o las mejoras de las colas de quórum de 4.x, que incluyen prioridades de mensajes y un límite de entregas predeterminado que impide que los mensajes envenenados (poison messages) circulen para siempre.
Si está entre 3.8 y 3.12, la respuesta es la misma, pero la ruta es más larga: llegue primero a 3.13, estabilice y luego pase a 4.x. Ejecutamos ambas mitades para nuestros clientes, y el servicio de actualizaciones y parches de RabbitMQ tiene ese alcance.
Que quedarse sea seguro es una pregunta distinta de si es posible: ¿sigue siendo seguro ejecutar RabbitMQ 3.x? repasa las fechas de fin de vida útil y la exposición a CVE serie por serie. Si se queda, el soporte LTS extendido para RabbitMQ 3.x mantiene la versión parcheada mientras la actualización espera una ventana.
El runbook de actualización progresiva que usamos
Esta es la secuencia que seguimos en los clústeres de nuestros clientes. Supone un clúster de tres o cinco nodos, colas de quórum para todo lo que importa y clientes que se reconectan al perder la conexión.
- Inventario. Registre las versiones, las versiones de Erlang, los plugins habilitados y todas las políticas. Ejecute
rabbitmq-diagnostics check_if_any_deprecated_features_are_usedyrabbitmq-diagnostics check_if_cluster_has_classic_queue_mirroring_policyen cualquier nodo. Ambos deben devolver un resultado limpio antes de continuar. - Habilite todos los feature flags estables.
rabbitmqctl enable_feature_flag allen un nodo se aplica a todo el clúster. Confírmelo conrabbitmqctl list_feature_flags; cualquier flag que siga endisabledbloquea la actualización. - Convierta las colas clásicas replicadas en colas de quórum, flujo por flujo. Las colas de quórum no se pueden convertir sobre la misma cola. Para cada flujo, declare la cola de quórum, redirija los consumidores, redirija los productores, drene la cola anterior y elimínela. Hágalo por aplicación, para que un error afecte a un solo flujo y no a todo el entorno.
- Verifique el Erlang de destino. Confirme que el paquete de OTP 26 o posterior está disponible en todos los nodos y que es la versión con la que se probó su compilación de 4.x.
- Exporte las definiciones y haga un respaldo.
rabbitmqctl export_definitionsmás un respaldo a nivel de sistema de archivos del directorio de datos en cada nodo. La exportación de definiciones es la base para reconstruir si se cruza el límite de reversión. - Actualice un nodo a la vez. Antes de detener un nodo, ejecute
rabbitmq-upgrade await_online_quorum_plus_onepara que ninguna cola de quórum pierda su mayoría mientras ese nodo está fuera. Luego,rabbitmq-upgrade drainpone el nodo en modo de mantenimiento, cierra ordenadamente las conexiones de los clientes y transfiere el liderazgo de las colas de quórum a otros nodos. Detenga el servicio, actualice Erlang si hace falta, actualice RabbitMQ, inícielo y confirme que volvió a unirse. - Espere a que los miembros de las colas de quórum se pongan al día.
rabbitmq-queues quorum_status <queue>en las colas con más carga, orabbitmq-diagnostics check_if_node_is_quorum_criticalen el siguiente nodo que piensa detener. No pase al siguiente nodo hasta que esta verificación sea exitosa. - Verifique que los clientes se reconectaron. En la interfaz de administración, la cantidad de conexiones del nodo actualizado debería volver a su nivel habitual. Si una biblioteca cliente no se reconecta, corríjala ahora, antes del siguiente nodo.
- Repita con cada nodo restante. Durante esta ventana, el clúster ejecuta 3.13 y 4.x de forma mixta. No cambie políticas, no agregue colas ni habilite nada nuevo hasta terminar con el último nodo.
- Habilite los nuevos feature flags de 4.x. Después de actualizar el último nodo, ejecute de nuevo
rabbitmqctl enable_feature_flag all. Este es el límite de reversión: una vez habilitado un feature flag exclusivo de 4.x, no hay forma de volver a una versión anterior. Todo lo previo a este paso se puede revertir restaurando un nodo a 3.13.
rabbitmqctl enable_feature_flag all
rabbitmq-upgrade await_online_quorum_plus_one
rabbitmq-upgrade drainBlue-green es la alternativa cuando el clúster es lo bastante pequeño para reconstruirlo, la exportación de definiciones es confiable y puede permitirse mover los clientes mediante DNS o el balanceador de carga. Le da un clúster 4.x limpio y un clúster 3.13 intacto al cual volver. Lo preferimos para clústeres que acumularon años de políticas no documentadas.
En cualquier caso, el soporte cubre la ventana de actualización con una respuesta de 15 minutos para P1, algo que importa sobre todo entre el paso 6 y el paso 10.
Preguntas frecuentes
¿Puedo actualizar directamente de RabbitMQ 3.13 a 4.x?
Sí. Se admite una actualización progresiva (rolling upgrade) de 3.13.x a 4.0.x, siempre que todos los feature flags estables estén habilitados, no quede ninguna política de réplica de colas clásicas y Erlang esté en OTP 26 o posterior. Si está en 3.12 o en una versión anterior, no puede saltar a 4.x; primero actualice a 3.13, habilite sus feature flags y después continúe. El motivo es que los nodos 4.x solo se unen a clústeres en los que el conjunto de feature flags de 3.13 está completamente habilitado, y las series anteriores no pueden cumplir esa condición.
¿Puedo quedarme en RabbitMQ 3.x?
Puede, pero solo de forma segura con un acuerdo de soporte que aplique backports de las correcciones de seguridad, porque los parches upstream para 3.x terminan con la ventana de soporte de la comunidad de 3.13. Nuestro soporte LTS extendido cubre de 3.8.x a 3.13.x con backports de parches de CVE precisamente para esta situación. Quedarse tiene sentido cuando una migración de clientes, un congelamiento por cumplimiento normativo o una conversión de colas necesita más tiempo del que permite el calendario upstream. No tiene sentido como estado permanente; planifique el paso a 4.x según su propio cronograma.
¿Cómo se actualiza RabbitMQ sin tiempo de inactividad?
Con una actualización progresiva, nodo por nodo. Habilite todos los feature flags, elimine las colas clásicas replicadas, exporte las definiciones y luego, en cada nodo, ejecute rabbitmq-upgrade await_online_quorum_plus_one, drénelo, actualice Erlang y RabbitMQ, reinícielo y espere a que los miembros de las colas de quórum se pongan al día antes de tocar el siguiente nodo. Los clientes que se reconectan al perder la conexión ven una breve reconexión, no una caída del servicio. La alternativa blue-green, con un nuevo clúster 4.x y un corte de clientes, es la opción cuando el clúster actual está demasiado enmarañado para actualizarlo in situ.
¿RabbitMQ 4 requiere Erlang 26?
Sí. RabbitMQ 4.x requiere Erlang/OTP 26 o posterior. Si sus nodos 3.13 ya están en OTP 26, el paso de Erlang no implica nada; si están en OTP 25, actualice Erlang en cada nodo durante la misma ventana progresiva que el paquete de RabbitMQ. Revise la tabla de compatibilidad para la versión de parche 4.x exacta que va a instalar, ya que las versiones 4.x posteriores elevan el mínimo. Nuestro artículo sobre el fin de vida útil de Erlang 26 explica qué significa eso para los plazos de soporte.