This topic describes how to migrate metadata from an open source RocketMQ cluster to a Message Queue for Apache RocketMQ instance in the Message Queue for Apache RocketMQ console.

Background information

The metadata migration feature allows you to migrate the configurations of open source RocketMQ topics and groups to Message Queue for Apache RocketMQ. Messages in the source topics are not migrated.

Message Queue for Apache RocketMQ provides a metadata export tool for you to export the metadata of an open source RocketMQ cluster as a JSON file. After you export the metadata as a file, you can import the file to a specified Message Queue for Apache RocketMQ instance in the Message Queue for Apache RocketMQ console. Then, Message Queue for Apache RocketMQ creates topics and groups in the specified instance based on the configurations in the metadata file. The names and numbers of topics and groups created by Message Queue for Apache RocketMQ are the same as those in the source RocketMQ cluster.

Prerequisites

  • A metadata file for migrating an open source RocketMQ cluster is imported, and a migration task is created. For more information, see Step 1: Create a migration task.
  • Technical evaluation and cost estimation are complete. For more information, see Step 2: Evaluate a migration task.
  • A Message Queue for Apache RocketMQ instance that meets the technical and cost requirements is created as the destination instance for migration. If no instances are available, create one. For more information, see Manage instances.

Migrate the metadata

  1. Log on to the Message Queue for Apache RocketMQ console.
  2. In the left-side navigation pane, click Migration to Cloud.
  3. In the top navigation bar, select a region, such as China (Hangzhou).
  4. On the Migration to Cloud page, find the required migration task and click Details in the Actions column.
  5. In the Migrate Metadata wizard, select the created Message Queue for Apache RocketMQ instance as the destination for metadata migration from the Destination Instance drop-down list, and click OK.
    The metadata of all the groups is automatically migrated in the background, but only the information about topics is displayed. To view the migration results of all resources, you must manually rectify the migration settings of all types of topics.
  6. Rectify the migration settings of all types of topics and click OK in the lower part of the page.
    1. Find a topic in the resource list, select a type for this topic from the drop-down list in the Message Type column, and then click Confirm and Import in the Actions column. You can also select multiple topics, select types for all selected topics at a time, and then click Batch Confirm and Import in the lower-left corner of the page.
    2. In the message that appears, click OK.
    You can view the information and migration results of all the topics and groups in the Migration Details section of the resource list. You can also filter topics or groups by name, type, or execution result to view the migration result of a specified topic or group.

Verify the results

If the migration succeeds, the migrated topics and groups are created in the destination Message Queue for Apache RocketMQ instance. You can view the topics and groups on the Topics and Groups tabs.

  1. Log on to the Message Queue for Apache RocketMQ console.
  2. In the left-side navigation pane, click Instances.
  3. In the top navigation bar, select a region, such as China (Hangzhou).
  4. On the Instances tab, click the name of the destination instance or click Details in the Actions column that corresponds to the instance.
  5. In the left-side pane, click Topics. Check whether the migrated topics exist in the topic list.
  6. In the left-side pane, click Groups. Check whether the migrated groups exist in the group list.

Possible causes of migration failures

The following table describes the possible causes of migration failures and how to resolve migration failures.
Possible cause Description
The specified topic already exists. An existing topic in the destination instance has the same name as the topic to be created. Specify another topic name.
The group ID that you want to create already exists. An existing group in the destination instance has the same ID as the group to be created. Specify another group name.
The specified instance does not exist. Check whether the destination instance exists on the Instances page.
Failed to verify permissions on the instance. Please try again after you confirm the permissions on the instance. Check the permissions of the destination instance.
The specified instance is not in service. View the status of the destination instance on the Instances page.
Failed to create the topic. The maximum number of topics on this instance is reached. Go to the Enterprise Platinum Edition Instances page to upgrade the instance. The number of topics in the destination instance has reached the upper limit. Delete topics that are no longer in use, or upgrade the instance. For more information, see the "Upgrade an instance" section in the Operations on Enterprise Platinum Edition instances topic.
The instance does not have required permissions. Check the permissions granted to and permission policies configured for the instance.
A topic name cannot be the same as a group ID. The specified topic name is the same as a group name. Specify another topic name.
A group ID cannot be the same as a topic name. The specified group name is the same as a topic name. Specify another group name.
The specified group ID belongs to another instance. An existing group in another instance has the same ID as the group to be created. Specify another group ID.
Failed to create the group ID. Please try again later. The group with the specified ID fails to be created. Try again later or submit a ticket for technical support.
Failed to create the topic. The topic fails to be created. Try again later or submit a ticket for technical support.
A system processing error occurred. Please contact the system administrator. An internal server error has occurred. Submit a ticket for technical support.
Failed to verify the parameters. One or more input parameters are empty or invalid. Submit a ticket for technical support.

What to do next

Step 4: Migrate the messaging service