Guía · RabbitMQ

Runbook de actualización de versión de RabbitMQ 3.x a 4.x

La secuencia de saltos soportada hasta RabbitMQ 4.4, los controles go/no-go que deben superarse antes de la ventana, la secuencia por nodo dentro de ella y lo que se puede y no se puede deshacer en cada etapa. Verificado con rabbitmq.com el 29 de octubre de 2026, junto con las notas de versión de 4.x.

Scott Sternloff

Por Scott Sternloff, Arquitecto empresarial sénior

LinkedIn · Actualizado el · 13 min de lectura · 8 secciones

En esta página

Dos saltos desde 3.13, y solo hacia delante una vez activadas las flags

Dos saltos desde 3.13, y solo hacia delante una vez activadas las flags

La versión actual es 4.4.0, y las actualizaciones progresivas (rolling upgrades) a 4.4 solo están soportadas desde 4.2.x o 4.3.x. Por tanto, los clústeres 3.13, 4.0 y 4.1 pasan primero por 4.2.x, y los 3.12 o anteriores llegan antes a 3.13. Un clúster 3.13 con Khepri activado no tiene ninguna ruta in situ: necesita una migración con despliegue blue-green.

  • Antes de la ventana: todas las feature flags estables activadas, ningún mirroring de colas clásicas en uso, khepri_db activado antes de salir de 4.2 y una versión de Erlang soportada por ambos extremos de cada salto.
  • Dentro de la ventana: un nodo cada vez, drenado primero y con su estado comprobado antes de detener el siguiente.
  • Rollback: no se admiten downgrades y una feature flag no puede desactivarse una vez activada. La única vuelta atrás documentada es el despliegue blue-green, redirigiendo las aplicaciones al clúster antiguo.

Para qué sirve este runbook

Esta es la checklist que se ejecuta el día de la intervención: saltos, controles, comandos y una tabla de rollback, en orden. Para la explicación extensa de por qué una actualización de 3 a 4 puede hacerse sin tiempo de inactividad, consulte el artículo sobre la actualización; para migraciones entre brokers o un paso masivo de colas clásicas a colas de quórum, consulte la guía de migración. Esta página enlaza a ambos en lugar de repetirlos.

Confirme que el salto es una actualización progresiva soportada

Solo los saltos siguientes están soportados como actualizaciones progresivas, así que planifique la ruta antes que nada. También se admiten las actualizaciones entre parches de una misma serie. Si entre dos versiones no se puede hacer una actualización progresiva, tampoco pueden coexistir en un mismo clúster.

Rutas de actualización progresiva soportadas de RabbitMQ (guía de actualización de rabbitmq.com, documentación de 4.4, verificado el 29 de octubre de 2026)
DesdeHasta¿Actualización progresiva?Notas
4.3.x4.4.xCon soporteAmbas funcionan con Erlang 27. Pase a Erlang 28 o 29 tras llegar a 4.4.0.
4.2.x4.4.xCon soporteLa ruta más corta desde 4.2. 4.2.9 y posteriores requieren Erlang 27.
4.2.x4.3.xCon soporteLa única ruta a 4.3; las notas de versión de 4.3.0 exigen antes el último parche de 4.2.x.
4.1.x4.2.xCon soporteDespués, de 4.2.x a 4.4.x.
4.0.x4.2.x o 4.1.xCon soportePase a 4.2.x y después de 4.2.x a 4.4.x.
3.13.x4.2.x, 4.1.x o 4.0.xCon soporteUse 4.2.x. 3.13 funciona con Erlang 26, así que aterrice en un parche de 4.2 que también soporte Erlang 26.2.
3.13.x, 4.0.x, 4.1.x4.3.x o 4.4.xNo soportadoActualice primero a 4.2.x.
3.13.x con Khepri activadoCualquier 4.xNo soportadoKhepri era experimental en 3.13 e incompatible con 4.x. Utilice un despliegue blue-green.
3.12.x3.13.xCon soporteNo existe ruta progresiva de 3.12 a 4.x; las notas de versión de 4.0 ofrecen el despliegue blue-green desde 3.12.14.
De 3.11.18 a 3.7.18Una serie másCon soporteDe 3.11.18 a 3.12, de 3.10 a 3.11, de 3.9 a 3.10, de 3.8 a 3.9, de 3.7.18 a 3.8: una serie cada vez.
Tabla · Rutas de actualización progresiva soportadas de RabbitMQ (guía de actualización de rabbitmq.com, documentación de 4.4, verificado el 29 de octubre de 2026). En pantallas pequeñas, desplácese lateralmente.

Secuencie la ruta desde 3.13 para que Erlang nunca bloquee una actualización progresiva

Ordene los pasos de modo que cada nodo ejecute siempre una versión de Erlang soportada tanto por la versión de RabbitMQ que abandona como por la que adopta. Así secuenciamos las actualizaciones desde 3.13, y así cada paso sigue siendo progresivo. La documentación recomienda actualizar Erlang junto con RabbitMQ cuando un mismo paso lo permite.

  1. 3.13.x con Erlang 26.2. Pase al último parche de 3.13.x disponible y active todas las feature flags estables; las notas de versión de 4.0 exigen todas las flags de 3.13 antes de salir de 3.x.
  2. Actualice a un parche de 4.2 que soporte Erlang 26.2 (de 4.2.0 a 4.2.8). 3.13 llega como máximo a Erlang 26.2.x, y 4.2.9 y posteriores requieren Erlang 27, así que este parche intermedio es lo que permite que ambas versiones compartan runtime.
  3. Actualice Erlang de 26.2 a 27.x sobre 4.2. Las versiones de 4.2.0 a 4.2.8 soportan de Erlang 26.2 a 27.x, así que este cambio también es progresivo.
  4. Actualice al último parche de 4.2.x y active todas las flags estables, incluida khepri_db. Khepri es el único almacén de metadatos (metadata store) desde 4.3, Mnesia desaparece y las notas de versión de 4.3.0 indican khepri_db como obligatoria.
  5. Deje que 4.2 se estabilice y después actualice de 4.2.x a 4.4.0 con Erlang 27. A continuación, active las feature flags de 4.4. No encadenamos los dos saltos seguidos; además, 4.4.0 corrigió un problema que podía hacer fallar una actualización de 3.13 a 4.2 seguida inmediatamente de un paso a 4.3.
  6. Opcionalmente, actualice Erlang a 28 o 29. 4.4.0 soporta plenamente ambas para actualizaciones progresivas. No lo haga en 4.2 ni en 4.3 anteriores a 4.3.6: ahí la documentación solo admite Erlang 28 para clústeres nuevos, porque los clústeres Khepri que pasan de 27 a 28 pueden sufrir un problema conocido de versiones mixtas.

Si el clúster 3.13 daba servicio a clientes AMQP 1.0 mediante el antiguo plugin rabbitmq_amqp1_0, las notas de versión de 4.3.0 piden al menos una actualización progresiva tras activar la flag rabbitmq_4.0.0 y antes de actualizar a 4.3.0; aplicamos la misma regla antes de 4.4.

Supere los controles go/no-go antes de la ventana

Todos los controles siguientes deben superarse días antes de la ventana, porque la mayoría no pueden corregirse dentro de ella. Ejecute cada comprobación en la versión que va a abandonar.

  1. Todas las feature flags estables activadas. La guía de actualización advierte de que, en caso contrario, la actualización puede fallar, y una flag no puede desactivarse una vez activada, así que es una decisión para tomar con calma, no a las 2 de la madrugada. rabbitmqctl list_feature_flags y después rabbitmqctl enable_feature_flag all.
  2. Ninguna funcionalidad obsoleta en uso. rabbitmq-diagnostics check_if_any_deprecated_features_are_used devuelve un código distinto de cero si hay alguna. Detecta el mirroring de colas clásicas, pero no el QoS global, así que revise el código cliente por separado para eso.
  3. Ningún mirroring de colas clásicas pendiente. El mirroring se eliminó en 4.0 y las claves de mirroring en las políticas simplemente dejan de tener efecto, de modo que una cola espejo (mirrored queue) se convierte sin ningún error en una cola clásica de una sola réplica. Migre a colas de quórum (quorum queues) las colas que necesiten replicación y elimine después las claves ha- de todas las políticas de cada vhost (rabbitmqctl list_policies --vhost <vhost>). Las políticas ha-mode residuales figuraban entre los hallazgos de una actualización de 3.13.7 a 4.2 que nos llamaron a recuperar.
  4. Khepri no estaba activado en 3.13. Compruebe khepri_db en rabbitmqctl list_feature_flags. Si está activado en 3.13, deténgase: no hay ruta in situ, solo despliegue blue-green.
  5. Las aplicaciones toleran los valores por defecto de 4.3. Desde 4.3.0, las colas transitorias no exclusivas, el QoS global y queue_master_locator se deniegan por defecto, y declarar una cola con x-queue-mode o x-queue-version=1 falla porque CQv1 se ha eliminado. Si una aplicación necesita realmente colas transitorias no exclusivas, establezca deprecated_features.permit.transient_nonexcl_queues = true en todos los nodos, y reinícielos, antes de la actualización.
  6. Claves de gestión de particiones de red eliminadas. Desde 4.3 las claves cluster_partition_handling se aceptan pero no tienen efecto, y con Khepri la mayoría de los nodos debe estar en línea para que el clúster esté disponible. Elimine las claves para que nadie las interprete como una protección.
  7. Un plan de Erlang para cada salto. Cada nodo debe ejecutar una versión de Erlang soportada por las dos versiones de ese salto; consulte el paso 2 y la matriz.
  8. El clúster está sano y puede funcionar con un nodo menos. Sin alarmas (rabbitmq-diagnostics check_alarms), sin sincronización de réplicas de colas o streams en curso y con rabbitmq-diagnostics check_if_node_is_quorum_critical superado en todos los nodos. Las conexiones y los líderes de las colas pasan a los nodos restantes mientras uno está caído, así que dimensione para ello.
  9. Copias de seguridad fuera del nodo. La documentación recomienda encarecidamente hacer copia de seguridad del directorio de datos de cada nodo, y un fichero de definiciones exportado convierte una reconstrucción en cuestión de minutos: rabbitmqctl export_definitions /path/off-node/definitions.json.
  10. Los clientes se reconectan por sí solos. Al detener un nodo se cierran sus conexiones de cliente; las aplicaciones necesitan recuperación automática y un balanceador de carga o una lista de hosts.
  11. Cambios incompatibles de 4.4 revisados. El descubrimiento de OpenID Connect se valida de forma más estricta (se sabe que afecta a Cloud Foundry UAA), GET /api/auth/hash_password ha pasado a ser POST y las cabeceras x-amqp-1.0-* escritas por nodos 3.13 y anteriores ya no se interpretan.
  12. Línea base e inventario de enlaces registrados. Profundidad de las colas, número de consumidores, conexiones y margen por nodo, además de cada upstream de Federation y cada Shovel (rabbitmqctl list_parameters --vhost <vhost>). Sin ello no podrá distinguir una regresión de un día normal, ni detectar el único enlace que no se ha restablecido.
  13. Las herramientas CLI coinciden con la versión del broker. Tras un salto de 3.12.14 a 3.13.14 hemos visto fallar rabbitmq-diagnostics y rabbitmqctl porque las herramientas empaquetadas no se sustituyeron junto con el servidor. Verifíquelas antes de necesitarlas para un diagnóstico.

Objetivos de respuesta desde 15 minutos, según el plan. Ingenieros sénior asignados.

Contacto

Ejecute la secuencia por nodo, de uno en uno

Actualice un nodo, compruebe que está sano y pase al siguiente; nunca dos a la vez. En un clúster de tres nodos deben seguir activos dos para que las colas de quórum, los streams y Khepri mantengan la mayoría.

  1. Control: el nodo puede detenerse con seguridad. rabbitmq-diagnostics check_if_node_is_quorum_critical debe superarse. En automatización, rabbitmq-upgrade await_online_quorum_plus_one bloquea hasta que haya suficientes nodos activos.
  2. Drénelo. rabbitmq-upgrade drain pone el nodo en modo mantenimiento: deja de aceptar conexiones, cierra las existentes y cede a sus pares los líderes de sus colas de quórum. Se espera que un nodo permanezca en este modo minutos, no horas.
  3. Detenga, actualice, arranque. RabbitMQ, sus herramientas CLI y, si este salto lo requiere, Erlang. Un reinicio saca automáticamente el nodo del modo mantenimiento; rabbitmq-upgrade revive solo sirve para un nodo drenado que haya decidido no reiniciar.
  4. Control: se ha reincorporado correctamente. rabbitmq-diagnostics check_running, rabbitmqctl cluster_status y rabbitmq-diagnostics check_alarms; después compare consumidores y profundidad de colas con la línea base. Continúe solo cuando coincidan.
  5. Repita con el siguiente nodo. Los clústeres de versiones mixtas existen para las actualizaciones progresivas y, según las notas de versión de 4.3.0, no deberían mantenerse más de unas pocas horas.
  6. Tras el último nodo: active las nuevas flags y haga el rebalanceo. rabbitmqctl enable_feature_flag all y después rabbitmq-queues rebalance all, porque los líderes quedan repartidos de forma desigual tras la actualización. Pida a los usuarios de la interfaz de gestión que borren la caché y el almacenamiento del navegador para su dominio.

Sepa qué puede deshacer en cada etapa

Las opciones de rollback se reducen en cada etapa, y la documentación no admite downgrades en absoluto: no están probados, y algunas versiones de parche no podían revertirse ni siquiera al parche anterior. Decida el punto de abandono antes de que se abra la ventana.

Opciones de rollback de la actualización de RabbitMQ por etapa (guías de actualización y de feature flags de rabbitmq.com, notas de versión de 4.4.0)
Etapa alcanzada¿Se puede volver atrás?Qué hacer
Controles superados, ningún nodo detenido aúnSíAbandone; no ha cambiado nada salvo las flags que activó en la versión antigua.
Algunos nodos actualizados, nuevas flags sin activarNo soportadoRecupere hacia delante: complete la actualización o reconstruya el nodo fallido con la versión mayoritaria y reincorpórelo. Restaure desde la copia de seguridad del directorio de datos solo como último recurso.
Feature flags de la nueva versión activadasNoUna feature flag no puede desactivarse una vez activada. Solo hacia delante; la exportación de definiciones es la vía de reconstrucción.
En 4.4 con datos de colas clásicas escritosNo4.4 escribe un nuevo formato v2 del almacén de mensajes; un nodo con ficheros v2 no puede revertirse a 4.3.x ni anteriores.
Despliegue blue-green: aplicaciones trasladadas, clúster antiguo aún en marchaSíRedirija las aplicaciones al clúster antiguo. Es el único rollback que describe la documentación; conserve el clúster antiguo hasta verificar el último consumidor.
Tabla · Opciones de rollback de la actualización de RabbitMQ por etapa (guías de actualización y de feature flags de rabbitmq.com, notas de versión de 4.4.0). En pantallas pequeñas, desplácese lateralmente.

Cuando algo falla: síntoma, causa y solución

  • Un nodo no se reincorpora tras su actualización. Un nodo solo puede reincorporarse si soporta todas las feature flags activadas en el clúster, de modo que una flag activada mientras estaba caído, o una discrepancia de versiones, lo deja fuera. Lleve su software a la versión mayoritaria y reincorpórelo; en nuestras recuperaciones, resetear ese nodo y dejar que tome los metadatos del clúster ha sido más rápido y seguro que revertir el resto.
  • Las declaraciones empiezan a fallar tras pasar a 4.3 o 4.4. Las colas transitorias no exclusivas, x-queue-mode y x-queue-version=1 ahora se rechazan, y el QoS global se deniega por defecto. Corrija la aplicación o permita la funcionalidad obsoleta en todos los nodos.
  • Una cola que antes era espejo perdió sus mensajes al caer un nodo. Su política ha- dejó de tener efecto en 4.0 y pasó a ser una cola clásica de una sola réplica. Conviértala en una cola de quórum.
  • Las herramientas CLI han dejado de funcionar. Las herramientas empaquetadas ya no coinciden con el broker. Reinstale el paquete correspondiente y compruébelo con rabbitmq-diagnostics status.
  • Se han reiniciado todos los enlaces de Federation. Es lo esperado durante la actualización: los enlaces de Federation de colas se ejecutan en el nodo del líder de la cola y se recrean tras cada elección de líder. Compare con el inventario de enlaces y restablezca lo que falte.
  • El throughput cayó tras pasar las colas espejo a colas de quórum. Las colas de quórum persisten cada mensaje antes de confirmarlo y lo replican. Use los discos más rápidos disponibles y dé a cada nodo al menos tres veces el límite efectivo de WAL en memoria (512 MiB por defecto), cuatro veces en sistemas de alto throughput. Desaconsejamos perseguir las cifras anteriores reduciendo el número de réplicas.
  • Los inicios de sesión OAuth 2 fallan tras 4.4. El proveedor de identidad no supera la validación de descubrimiento más estricta. Establezca auth_oauth2.discovery.verify_issuer y/o auth_oauth2.discovery.verify_https_endpoints a false antes de actualizar para proveedores como Cloud Foundry UAA.

Cuándo optar por un despliegue blue-green

Opte por un despliegue blue-green cuando se cumpla cualquiera de las condiciones siguientes. La documentación lo considera la estrategia más segura y lo recomienda siempre que una actualización progresiva no sea viable, a costa de mantener dos clústeres durante un tiempo.

  • Khepri estaba activado en 3.13. No hay ruta in situ a 4.x.
  • El clúster está en 3.12 o anterior. La ruta progresiva a 4.4 supone al menos tres saltos (de 3.12 a 3.13, a 4.2 y a 4.4), cada uno con su propia ventana.
  • El entorno está lleno de colas espejo. rabbitmqadmin v2 automatiza el paso de colas espejo de 3.13.x a colas de quórum como migración blue-green.
  • Los nodos están en un sistema operativo que iba a sustituir de todos modos.
  • Necesita un ensayo. Un clúster paralelo permite que la aplicación funcione contra 4.4 antes que cualquier tráfico de producción.

La secuencia documentada es: desplegar el nuevo clúster, sincronizar los metadatos, configurar Federation, trasladar los consumidores, drenar los mensajes, trasladar los publicadores y retirar el clúster antiguo. Cuando hemos presupuestado ambas rutas para un entorno grande o antiguo, el clúster paralelo ha sido a menudo la opción que recomendamos.

Preguntas frecuentes

¿Puedo actualizar RabbitMQ 3.13 directamente a 4.4?

No. Las actualizaciones progresivas a 4.4 solo están soportadas desde 4.2.x o 4.3.x, así que un clúster 3.13 pasa de 3.13.x a 4.2.x y después de 4.2.x a 4.4.x. Un clúster 3.13 con Khepri activado no puede actualizarse in situ en absoluto y necesita un despliegue blue-green.

¿Se puede hacer rollback de una actualización de RabbitMQ?

No in situ. RabbitMQ no admite downgrades, una feature flag no puede desactivarse una vez activada y un nodo 4.4 que haya escrito el nuevo formato del almacén de mensajes de colas clásicas no puede volver a 4.3.x. El único rollback documentado es el despliegue blue-green: redirigir las aplicaciones al clúster antiguo.

¿Requiere tiempo de inactividad actualizar RabbitMQ de 3 a 4?

No para el broker. Una actualización progresiva detiene un nodo cada vez y la documentación indica que no es necesario detener todos los nodos. Erlang puede actualizarse también de forma progresiva si cada nodo ejecuta una versión soportada por las dos versiones de RabbitMQ de ese salto; por eso la ruta desde 3.13 aterriza en un parche de 4.2 que aún soporta Erlang 26.2 antes de pasar a Erlang 27.

¿Por qué ha fallado mi actualización de RabbitMQ a mitad de proceso?

Las causas habituales son una feature flag estable sin activar, un nodo que no recibió una flag activada mientras estaba caído o aplicaciones que declaran colas que 4.3 ahora rechaza, como colas transitorias no exclusivas o x-queue-mode. Las tres se detectan en los controles previos si los ejecuta antes de la ventana.

¿Qué pasa con las colas clásicas en espejo (classic mirrored queues) al actualizar a RabbitMQ 4?

El mirroring se eliminó en 4.0. Las partes de mirroring de las políticas dejan de tener efecto y las colas siguen funcionando como colas clásicas de una sola réplica, por lo que pierden su redundancia sin ningún error. Migre a colas de quórum las colas que necesiten replicación antes de la actualización.

Consulta gratuita

Que un experto revise su clúster de RabbitMQ

Tanto si está resolviendo un incidente en producción como si planifica una migración o quiere una segunda opinión sobre su arquitectura, nuestro equipo está preparado. Sin discursos comerciales, solo respuestas.

Escríbanos