This topic describes how to migrate the metadata of an open source RabbitMQ cluster to an Alibaba Cloud Message Queue for RabbitMQ instance.

Prerequisites

  • The RabbitMQ management plug-in is enabled for the RabbitMQ cluster whose metadata you want to migrate. You can use the RabbitMQ console or HTTP API to export the metadata of the RabbitMQ cluster only after the plug-in is enabled. For more information, see Enable the RabbitMQ management plug-in.
  • A Message Queue for RabbitMQ instance to which you want to migrate the metadata is created. For more information, see Create a Message Queue for RabbitMQ instance.

Background information

The metadata of a RabbitMQ cluster includes information about the users, vhosts, queues, exchanges, binding keys, permissions, and parameters of the cluster. The metadata is stored in an internal database of the cluster and is automatically replicated to all nodes of the cluster. Each node has a metadata replica. When the metadata of a node changes, the metadata of all nodes is synchronously updated. Therefore, the metadata files exported from all nodes of the cluster are the same. To back up the metadata of a cluster, you can export the metadata to a JSON file and import the file to another RabbitMQ cluster.

Metadata migration to the cloud in this topic refers to the process of migrating the metadata of a RabbitMQ cluster to a Message Queue for RabbitMQ instance. Message Queue for RabbitMQ is a fully managed message queue service provided by Alibaba Cloud. This service is compatible with open source RabbitMQ. After you export the metadata file of a RabbitMQ cluster and import the file to a Message Queue for RabbitMQ instance, Message Queue for RabbitMQ creates vhosts, queues, exchanges, and bindings in the Message Queue for RabbitMQ instance based on the imported metadata. This way, the metadata of the cluster is migrated to the cloud.

Precautions

  • The metadata file in the JSON format that you want to import must contain a vhosts list, and the exchanges, queues, and bindings lists in the file must contain vhost information. For more information, see sample.json.
  • The vhost, exchange, queue, and binding information in the metadata file must comply with the limits on resource quantity and limits on characters used to name resources in Message Queue for RabbitMQ. For more information, see Limits.
  • If the metadata file contains more than 10 vhosts, we recommend that you split the metadata file and import the metadata in batches. For more information, see How do I split a metadata file?
  • If you want to import only a part of the vhosts for a RabbitMQ cluster, we recommend that you export the metadata file in the JSON format, delete the unneeded vhosts from the vhosts list in the exported file, and then import the file. For more information, see How do I export only some of the vhosts in a RabbitMQ cluster?

Metadata compatibility

Due to the differences in access control mechanisms between open source RabbitMQ and Message Queue for RabbitMQ, some metadata of RabbitMQ clusters cannot be imported to Message Queue for RabbitMQ instances. The unsupported metadata is automatically ignored during the import. The following table describes the metadata compatibility of RabbitMQ clusters with Message Queue for RabbitMQ instances.

Metadata Description Compatible
rabbit_version The version of a RabbitMQ cluster. No
users The users of a RabbitMQ cluster. No
Notice If your RabbitMQ cluster has users, you can use Resource Access Management (RAM) to implement the original user management mechanism after the metadata of the cluster is migrated to a Message Queue for RabbitMQ instance. For more information, see Create a RAM user.
vhosts The vhosts of a RabbitMQ cluster. Yes
permissions The permissions of RabbitMQ cluster users to manage vhosts. No
Notice If your RabbitMQ cluster allows users to manage vhosts, you can use RAM to grant users the permissions to manage vhosts after the metadata of the cluster is migrated to a Message Queue for RabbitMQ instance. For more information, see RAM policies.
parameters The runtime parameters for a RabbitMQ cluster. No
global_parameters The global runtime parameters for a RabbitMQ cluster. No
policies The vhost runtime parameters for a RabbitMQ cluster. Policies specify the optional parameters for the exchanges and queues of a vhost. No
Notice If your RabbitMQ cluster is configured with vhost runtime parameters, you can configure the optional parameters when you create exchanges and queues in the Message Queue for RabbitMQ console. The optional parameters cannot be modified after the exchanges and queues are created. To modify the parameters for an exchange or queue, you must delete the exchange or queue and create it again. For more information, see Create an exchange and Create a queue.
queues The queues of a RabbitMQ cluster. Yes
exchanges The exchanges of a RabbitMQ cluster. Yes
bindings The bindings between the exchanges and queues of a RabbitMQ cluster. Yes

Migrate metadata

  1. Log on to the Message Queue for RabbitMQ console.
  2. In the top navigation bar, select the region where your instance resides.
  3. In the left-side navigation pane, click Migration.
  4. In the 1. Export Metadata step of the Migration page, select an export method and click Next.
    • Open source RabbitMQ console
      1. Visit the RabbitMQ logon page from a browser.

        The URL is http://<RabbitMQ IP address>:15672/.

      2. On the RabbitMQ logon page, enter your username in the Username field and your password in the Password field, and click Login.
      3. On the Overview tab, expand Import/export definitions. Select All from the Virtual host drop-down list in the Export section. Then, click Download broker definitions.
      4. In the Save As dialog box, select the path where you want to save the metadata file of the RabbitMQ cluster and click Save.
    • RabbitMQ HTTP API
      1. Open the terminal.
      2. Run the following command to export the metadata file of the RabbitMQ cluster:
        wget --user <RabbitMQ account> --password <RabbitMQ password> http://<RabbitMQ IP address>:15672/api/definitions -O <Path of the metadata file>
    The metadata file is exported to the storage path of the file.
  5. In the 2. Import Metadata step, click Import Metadata.
    pg_select_to_import
  6. In the Open dialog box, select the metadata file in the storage path and click Open.
  7. In the OK message, click OK.
    The import result is displayed in the Import Result section of the Migration page.
    Notice If a vhost fails to be imported, you must modify the metadata file based on the failure cause in the Description column and import the metadata file again. Message Queue for RabbitMQ implements idempotent processing on imported metadata. Therefore, repeated import of metadata does not affect your business.
    Parameter Description
    Vhost The name of an imported vhost.
    Import Result Specifies whether a vhost is imported.
    • Succeeded: The vhost is imported.
    • Failed: The vhost is not imported.
    Description Detailed information about the import result.
    • If the import succeeded, two hyphens (-) are displayed.
    • If the import failed, the cause of failure is displayed.