All Products
Search

This Product

    ApsaraMQ for RabbitMQ:Migrating from open-source

    Document Center

    ApsaraMQ for RabbitMQ:Migrating from open-source

    Last Updated:Jun 20, 2026

    If you use a self-managed RabbitMQ cluster and want to address stability issues such as message backlogs and split-brain, or achieve high concurrency, a distributed architecture, and flexible scaling, you can migrate your cluster to Message Queue for RabbitMQ. This topic describes how to migrate your cluster, including prerequisites and key considerations.

    Before you begin

    Message Queue for RabbitMQ is an advanced message queuing service developed by Alibaba Cloud based on proprietary distributed message storage technology. It strictly adheres to the AMQP 0-9-1 protocol, but it is not just a managed version of open-source RabbitMQ. The architecture of Message Queue for RabbitMQ effectively prevents stability issues such as memory leaks and server failures caused by message backlogs, and solves the split-brain problem in distributed systems. Additionally, it offers high scalability and a flexible pay-as-you-go billing model, enhancing service elasticity and reducing costs.

    However, Message Queue for RabbitMQ differs from open-source RabbitMQ in the implementation of some features. Therefore, before you consider migrating to Message Queue for RabbitMQ, you need to conduct a technical capability and cost-benefit evaluation to ensure that the selection meets your needs.

    Pre-migration assessment

    Technical assessment

    • Message Queue for RabbitMQ and open-source RabbitMQ differ in features, service, performance, exchanges, and queues. Before migrating to Message Queue for RabbitMQ, review these differences to determine if Message Queue for RabbitMQ meets your needs. For a detailed comparison, see Comparison with open-source RabbitMQ.

    • Message Queue for RabbitMQ imposes limits on clusters, API calls, and characters. Before migrating, evaluate whether these limits meet your business requirements. For more information, see Instance types.

    • We recommend choosing a dedicated serverless instance. These instances support open-source authentication and permissions, allowing for a seamless migration from open-source RabbitMQ to the cloud.

    Cost assessment

    Message Queue for RabbitMQ offers both subscription and serverless instances with various specifications. For differences between instance specifications, see Instance types.

    Compared to subscription instances, serverless instances provide better elasticity and cost advantages. For billing rules, see Billing for serverless instances.

    Use the following methods to estimate your self-managed RabbitMQ cluster's send/receive operations, queue count, and message volume.

    • Number of queues: On the Overview page of the open-source RabbitMQ console, view Global counts to obtain the number of metadata objects such as Queues and Exchanges.

    • Number of send/receive operations and message volume:

      • Method 1: On the Overview page of the open-source RabbitMQ management console, view Message rates and calculate the sum of the Publish, Deliver (manual ack)/Deliver (auto ack), and Redelivered metrics.image

      • Method 2: Use a Prometheus Grafana dashboard to view the cluster-wide QPS and message volume for inbound and outbound message traffic.

    Migration procedure

    Migrate metadata

    To migrate metadata, you export the metadata from your open-source RabbitMQ cluster and import it into your Message Queue for RabbitMQ instance. After a successful import, Message Queue for RabbitMQ creates the corresponding vhosts, queues, exchanges, and bindings in the target Message Queue for RabbitMQ instance. For detailed steps, see Migrate metadata to the cloud.

    Create users

    Open-source clients must use a username and password to authenticate with a Message Queue for RabbitMQ broker. Connections are established only upon successful authentication. Message Queue for RabbitMQ supports the following two identity and permission management modes. For more information, see User and permission management.

    • Open-source authentication and authorization

      You can create custom usernames and passwords, and manage permissions by importing metadata .

    • Resource Access Management (RAM)

      You can generate usernames and passwords from the AccessKey ID and AccessKey Secret of a RAM user.

    Establish a network connection

    Message Queue for RabbitMQ provides a PrivateLink endpoint. This endpoint allows you to establish a network connection to the cloud by using Cloud Enterprise Network (CEN).

    If you use the open-source authentication and authorization mode and have already configured a PrivateLink endpoint, you can skip this step.

    Migrate message data

    Migration strategy

    To ensure a smooth migration, migrate message data on a per-vhost basis. This involves switching client connection configurations and using the RabbitMQ Shovel plug-in.

    Benefits

    • Ensures smooth business migration.

    • Guarantees no data loss.

    • Eliminates the need to map complex mesh topologies of inter-application calls.

    Migration steps

    Choose the appropriate migration steps based on your business scenario:

    • For zero-downtime migration:

      • If a queue's producers and consumers are in the same application, see Scenario 1.

      • If a queue's producers and consumers are in separate applications, see Scenario 2.

      • For complex scenarios where the self-managed RabbitMQ cluster is already running Shovel tasks, see Scenario 3 .

    • For migration with a maintenance window: If your business can tolerate brief downtime, see Scenario 4.

    Scenario 1: Zero-downtime migration (unified applications)
    image

    1. Start with a canary release: switch a few service nodes to the cloud instance by updating their client configurations. Verify the following:

      1. Producers can send messages to the cloud queue.

      2. Consumers can consume messages from the cloud queue.

      3. End-to-end functionality and performance meet expectations.

    2. After confirming the canary nodes are working correctly, configure and enable the Shovel plug-in on your self-managed RabbitMQ cluster. This will migrate the existing backlogged messages from queues in the specified vhost to the corresponding queues in the cloud instance.

    3. Switch the RabbitMQ connection configuration to the cloud instance for all remaining service nodes by using a rolling update. At this point:

      1. All new messages are written directly to the cloud queues.

      2. All consumers fetch messages from the cloud queues.

      3. The self-managed cluster no longer receives new messages and only serves as the source for the Shovel to drain the remaining backlog.

    4. Monitor the message backlog on the self-managed cluster queues. Once the backlog is cleared, stop the Shovel task.

    5. You can check the backlog for a vhost's queues on the management console of your self-managed RabbitMQ cluster. A queue's backlog is cleared when its ready and unacknowledged message counts are both 0.

      In the RabbitMQ Management console, on the Queues page, the Messages group shows the number of ready messages in the Ready column and the number of unacknowledged messages in the Unacked column.

      Important

      If your code sends delayed messages to an x-delayed-message exchange, these messages do not enter the queue or count toward the backlog until their delay period expires. Before you stop the Shovel task, wait for a period at least as long as the maximum configured message delay to ensure that all delayed messages enter their queues.

    Scenario 2: Zero-downtime migration (separate applications)
    image

    1. Configure and enable the Shovel plug-in on your self-managed RabbitMQ cluster to migrate the existing backlogged messages from all relevant queues in the target vhost to the corresponding queues in the cloud instance.

    2. Start the consumer services for the cloud RabbitMQ instance so they begin fetching messages from the cloud queues.

    3. After verifying that the cloud consumers are working correctly, stop the consumer services connected to the self-managed cluster.

    4. Start the producer services for the cloud RabbitMQ instance. Verify that new messages are successfully published to the cloud queues and are processed by the consumers.

    5. After confirming that new messages are flowing into the cloud queues and being consumed correctly, stop the producer services connected to the self-managed cluster.

    6. At this point, all new messages go directly to the cloud queues, while the Shovel continues to move any remaining messages from the self-managed cluster.

    7. Monitor the message backlog on the self-managed cluster queues. Once the backlog is cleared, stop the Shovel task.

    Scenario 3: Zero-downtime migration (with existing Shovel tasks)
    image

    1. Stop the producer and consumer services connected to the self-managed cluster, and update their configurations to point to the cloud RabbitMQ instance.

    2. Start the producer and consumer services connected to the cloud instance and verify that they are working correctly.

    3. On the self-managed cluster, configure a new Shovel task (Shovel A) to migrate the message backlog from all relevant queues in vhost A to the corresponding queues in the cloud instance.

    4. Pause the existing Shovel task (Shovel B) that moves messages from vhost B to vhost A. Modify Shovel B's destination to point to the corresponding queue in the cloud RabbitMQ instance, and then re-enable Shovel B.

    5. Monitor the message backlog in the queues of vhost B on the self-managed cluster. Once the backlog is cleared, delete the Shovel B task.

    6. Monitor the message backlog in the queues of vhost A on the self-managed cluster. Once the backlog is cleared, delete the Shovel A task.

    Scenario 4: migration with downtime
    image

    1. Stop the producer and consumer services connected to the self-managed cluster.

    2. Update the RabbitMQ configuration in your services to point to the cloud RabbitMQ instance.

    3. Start the producer and consumer services for the cloud instance and verify that they are working correctly.

    4. On your self-managed RabbitMQ cluster, configure and enable the Shovel plug-in to migrate all remaining messages from the queues to the corresponding queues in the cloud instance.

    5. Monitor the message backlog on the self-managed cluster queues. Once the backlog is cleared, stop the Shovel task.

    Using the Shovel plug-in

    1. Log in to your self-managed cluster and run the following command in the command line to enable the Shovel plug-in:

      rabbitmq-plugins enable rabbitmq_shovel rabbitmq_shovel_management

    1. Log in to the management console of your self-managed RabbitMQ cluster. In the top navigation bar, click Admin, and then click Shovel Management on the right. In the Add a new shovel section, configure the Source and Destination, then click Add shovel.

      1. Source configuration format: For the URI, enter amqp://{username}:{password}@{ip}:{port}/{vhost}. In this URI: username and password are your credentials, ip is the IP address of your self-managed cluster, port is the communication port (typically 5672), and vhost is the source vhost.

      2. Destination configuration format: For the URI, enter amqp://{username}:{password}@{endpoint}:{port}/{vhost}. In this URI: username and password are the static credentials created in the Message Queue for RabbitMQ console, endpoint is the endpoint address of your Message Queue for RabbitMQ instance, port is 5672, and vhost is the destination vhost.

      You must also configure the Virtual host, a required Name, the protocol (such as AMQP 0.9.1), and the source and destination queue names. Other parameters include Prefetch count, Auto-delete (default is Never), Add forwarding headers (default is No), Reconnect delay, and Acknowledgement mode (default is On confirm).

    2. After the Shovel is added, go to the Shovel Status page to check its status. A 'running' state indicates the task started successfully.

    3. Once the message backlog in the queues of your self-managed RabbitMQ cluster is cleared, delete the Shovel task.

      On the Shovel details page, expand the Delete this shovel section at the bottom and click the Delete this shovel button.

    References

    For more information about the Shovel plug-in, see the Shovel Plugin documentation.