Migración desde HiveMQ sin interrupciones: dos brokers MQTT en paralelo y clientes por oleadas

La forma más segura de dejar HiveMQ Cloud Serverless sin interrumpir el servicio es mantener ambos brokers en paralelo durante un tiempo y retransmitir los mensajes entre ellos. Así, dispositivos y aplicaciones pueden moverse grupo a grupo, y un dispositivo que todavía está en HiveMQ sigue hablando con una aplicación que ya se ha movido. Este artículo muestra cómo construir ese relay, cómo evitar bucles de mensajes y cómo mover los clientes por oleadas antes de la fecha límite del 31 de diciembre de 2026.

Por qué hace falta un relay

Ni HiveMQ Cloud Serverless ni un broker gestionado en la nube como ConnectMQ harán de puente hacia otro broker por ti en el lado cloud. La solución es un pequeño proceso relay que ejecutas tú: se conecta a ambos brokers como un cliente MQTT normal, se suscribe a determinados topics en un lado y los vuelve a publicar en el otro. Como es solo un cliente, funciona con cualquier broker basado en estándares y no necesita permisos especiales.

 devices (still on HiveMQ) --> HiveMQ Serverless --relay--> ConnectMQ --> moved consumers
 moved command senders     --> ConnectMQ        --relay--> HiveMQ Serverless --> devices

Si ya ejecutas Mosquitto en tus instalaciones, su función de bridge puede hacer el mismo trabajo; consulta migrar Mosquitto a un broker MQTT en la nube y la configuración de bridge en Mosquitto.

El problema de los bucles y cómo evitarlo

Si el relay reenvía el topic site1/# de HiveMQ a ConnectMQ y también de ConnectMQ a HiveMQ, cada mensaje rebota de un lado a otro indefinidamente. Evita los bucles desde el diseño:

• Reenvía en una sola dirección. La telemetría va en un sentido (del antiguo al nuevo) y los comandos en el otro (del nuevo al antiguo). No reenvíes el mismo filtro de topic en ambas direcciones.
• Usa No Local de MQTT 5 en las suscripciones para que el relay no reciba sus propias publicaciones en el mismo broker.
• Marca los mensajes retransmitidos con una propiedad de usuario de MQTT 5, como relayed=1, y descarta los mensajes que ya la lleven.

El siguiente script aplica las tres medidas.

Un relay completo en Python

Este relay usa paho-mqtt 2.x y MQTT 5 en ambos lados. La telemetría y el estado van de HiveMQ a ConnectMQ; los comandos, de ConnectMQ a HiveMQ.

# pip install "paho-mqtt>=2.0"
import os, ssl
import paho.mqtt.client as mqtt
from paho.mqtt.packettypes import PacketTypes
from paho.mqtt.properties import Properties
from paho.mqtt.subscribeoptions import SubscribeOptions

# Filtros de topic por dirección (nunca pongas el mismo filtro en ambas)
OLD_TO_NEW = ["site1/+/telemetry", "site1/+/status"]
NEW_TO_OLD = ["site1/+/cmd"]

def make_client(client_id, user, password):
    c = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2, client_id=client_id, protocol=mqtt.MQTTv5)
    c.username_pw_set(user, password)
    c.tls_set(cert_reqs=ssl.CERT_REQUIRED)
    c.reconnect_delay_set(min_delay=1, max_delay=60)
    return c

old = make_client("relay-old-1", os.environ["HIVEMQ_USER"], os.environ["HIVEMQ_PASSWORD"])
new = make_client(os.environ["CMQ_CLIENT_ID"] + "_relay", os.environ["CMQ_USER"], os.environ["CMQ_PASSWORD"])

def is_relayed(msg):
    props = getattr(msg, "properties", None)
    return any(k == "relayed" for k, _ in (getattr(props, "UserProperty", None) or []))

def forward(target):
    def on_message(client, userdata, msg):
        if is_relayed(msg):
            return
        props = Properties(PacketTypes.PUBLISH)
        props.UserProperty = [("relayed", "1")]
        target.publish(msg.topic, msg.payload, qos=min(msg.qos, 1), retain=msg.retain, properties=props)
    return on_message

def subscriber(filters):
    def on_connect(client, userdata, flags, reason_code, properties):
        print("connected:", reason_code, "subscribing to", filters)
        opts = SubscribeOptions(qos=1, noLocal=True)
        for f in filters:
            client.subscribe(f, options=opts)
    return on_connect

old.on_connect, old.on_message = subscriber(OLD_TO_NEW), forward(new)
new.on_connect, new.on_message = subscriber(NEW_TO_OLD), forward(old)

old.connect(os.environ["HIVEMQ_HOST"], 8883)
new.connect("broker.connectmq.com", 8883)
new.loop_start()
old.loop_forever()

Ejecútalo en un host fiable cercano a ambos brokers, por ejemplo una pequeña VM en la nube o un contenedor, con las credenciales en variables de entorno. El QoS se limita a 1 para que el relay funcione en el plan Serverless gratuito; súbelo a 2 en Serverless (Paid) y superiores si tus flujos lo necesitan. Los flags retain se conservan, así que los mensajes de estado retenidos publicados en HiveMQ también aparecen como retenidos en ConnectMQ.

Dos notas prácticas:

• El relay cuenta como una conexión en cada broker. Inclúyelo al dimensionar el nuevo plan.
• Monitorízalo como si fuera producción. Si el relay se detiene, también se detienen los mensajes entre clientes movidos y no movidos. Ejecútalo con systemd o con una política de reinicio de contenedores.

El plan de oleadas

Mueve los clientes en un orden que mantenga funcionando todos los flujos de datos.

Después de cada oleada, comprueba:

• Que el número de conexiones en el dashboard de ConnectMQ coincide con el número de clientes movidos.
• Que los topics esperados aparecen en el explorador de topics en vivo.
• Que el estado de conexión de cada cliente en $SYS/broker/connection/{clientId}/state muestra en línea los dispositivos movidos.
• Que ningún cliente movido sigue conectándose a HiveMQ (revisa la consola de HiveMQ).
• Que el número de conexiones se mantiene dentro de los límites del plan; los clientes MQTT 5 reciben 0x97 si se supera una cuota.

Marcha atrás

Mientras el clúster antiguo siga funcionando, cualquier oleada se puede revertir restaurando los ajustes de conexión anteriores. Mantén los ajustes antiguos disponibles en tu sistema de aprovisionamiento hasta completar la última oleada. Esa es la razón principal para no dejar la migración para los últimos días de diciembre: después del 31 de diciembre de 2026 no habrá nada a lo que volver.

Checklist del cambio final

1. Todos los dispositivos y aplicaciones funcionan en el nuevo broker.
2. La consola de HiveMQ no muestra conexiones de clientes salvo el relay.
3. El estado retenido está presente en el nuevo broker, republicado por los dispositivos o restaurado desde una exportación. Consulta el borrado de datos de HiveMQ Serverless.
4. Detén el relay y vigila durante un día por si algún cliente reaparece en HiveMQ.
5. Elimina el clúster HiveMQ Serverless y quita el hostname antiguo de la configuración, los valores por defecto del firmware y la documentación.

Para el proceso completo de principio a fin, consulta la guía de migración de HiveMQ Serverless. Puedes construir y probar el relay hoy mismo contra un broker gratuito en app.connectmq.com.

Preguntas frecuentes

¿Puede HiveMQ Cloud hacer de puente directamente con ConnectMQ?

No en el lado cloud. Ejecuta un cliente relay como el script anterior, o un bridge de Mosquitto en tu propia infraestructura, que se conecte a ambos brokers como un cliente MQTT normal.

¿Notarán los dispositivos la migración?

Los dispositivos que se mueven ven una breve reconexión cuando cambian sus ajustes. Los que aún no se han movido no notan ningún cambio, porque el relay mantiene sus datos fluyendo hacia las aplicaciones ya movidas.

¿Añade latencia el relay?

Añade un salto más, normalmente de unos pocos milisegundos a decenas de milisegundos según dónde se ejecute. Colócalo cerca de ambos brokers y retíralo cuando termine la migración.

¿El relay debería usar QoS 1 o QoS 2?

QoS 1 es una buena opción por defecto y funciona en todos los planes de ConnectMQ. Asegúrate de que los consumidores toleran algún duplicado ocasional, que QoS 1 permite. Usa QoS 2 solo donde los duplicados sean inaceptables y tu plan lo admita.