Migrating a VMware Tanzu RabbitMQ for VMs Service Instance to Another Service Instance

Note: Pivotal Platform is now part of VMware Tanzu. In v1.20 and later, VMware Tanzu RabbitMQ [VMs] is named VMware Tanzu RabbitMQ for VMs.

This topic describes how to safely and fully migrate a Tanzu RabbitMQ service instance to another service instance. This migration can include migrating policies, parameters, and messages.

Migrate a Tanzu RabbitMQ Service Instance to Another Service Instance

To migrate from one service instance to another, do the following:

1. Create a new service instance. VMware recommends using the on-demand service for new deployments. For instructions, see Create a Service Instance.

2. If the RabbitMQ client in your apps has not defined the model for you, create queues, exchanges, and bindings on the new service instance that match your old service instance.

3. Migrate policies and parameters. For instructions, see Migrate Policies and Parameters below.

4. If you need all the messages in the old service instance, migrate the messages in the queues. For instructions, see Migrate Messages in Queues below.

5. When ready, delete your old instance. For instructions, see Delete a Service Instance.

6. If you have service-keys for the old instance, create service-keys for the new instance and replace the old credentials.

Migrate Policies and Parameters

If your old instance uses any of the following, ensure that you apply them to the new instance:

• Policies
• Virtual host-specific parameters, such as max_connections

Note: You can also apply them in the RabbitMQ Management UI. The API is the faster option if you have multiple instances to migrate.

1. Create a service key for the new instance with the admin username and password by running the following command:

    cf create-service-key SERVICE-INSTANCE SERVICE-KEY -c '{"tags": "administrator"}'
   

   Where:

   • SERVICE-INSTANCE is your service instance
   • SERVICE-KEY is a name of your choice for your service key

2. Retrieve the admin username and password with the following command:

    cf service-key SERVICE-INSTANCE SERVICE-KEY
   

   Where:

   • SERVICE-INSTANCE is your service instance
   • SERVICE-KEY is the service key name you chose in the step above

3. Retrieve the URL of the new service instance with the following command:

      cf service SERVICE-INSTANCE
   

   Where SERVICE-INSTANCE is your service instance.

4. Export the virtual host (vhost) limit parameters JSON to a local file with the following command:

      curl -u USERNAME:PASSWORD OLD-MANAGEMENT-URL/api/definitions/VHOST | jq '{"parameters":[.parameters[]]}' > PATH-TO-FILE
   

   Where:

   • USERNAME is the admin username for the cluster
   • PASSWORD is the admin password for the cluster
   • OLD-MANAGEMENT-URL is the RabbitMQ Management UI URL for your old service instance
   • VHOST is your virtual host ID

5. Upload the virtual host limit parameters JSON to the new instance with the following command:

    curl -H 'Content-type: application/json' -i -XPOST -u USERNAME:PASSWORD NEW-MANAGEMENT-URL/api/definitions/VHOST -d "$(cat PATH-TO-FILE)"
   

   Where:

   • USERNAME is the admin username for the cluster
   • PASSWORD is the admin password for the cluster
   • NEW-MANAGEMENT-URL is the RabbitMQ Management UI URL for your new service instance
   • VHOST is your virtual host ID

6. Export the policies JSON to a local file with the following command:

    curl -u USERNAME:PASSWORD OLD-MANAGEMENT-URL/api/definitions/VHOST | jq '{"policies":[.policies[]]}' > PATH-TO-FILE
   

7. Upload the policies JSON to the new instance with the following command:

    curl -H 'Content-type: application/json' -i -XPOST -u USERNAME:PASSWORD NEW-MANAGEMENT-URL/api/definitions/VHOST -d "$(cat PATH-TO-FILE)"
   

Migrate Messages in Queues

To safely migrate messages from one service instance to another, you must do one of the following:

• Migrate Messages Using the RabbitMQ Shovel Plugin
• Migrate Messages By Using Consumers to Drain the Old Service Instance

Use of the shovel plugin requires less waiting time and manual steps, however, it does not preserve the ordering of messages.

Migrate Messages Using the RabbitMQ Shovel Plugin

You can safely migrate messages to the new instance by using a shovel to move messages between queues on the two instances. For more information, see the RabbitMQ documentation.

1. Log in to the RabbitMQ Management Web UI for both the old and new service instances. For instructions about how to do so with or without OAuth enabled, see Using the RabbitMQ Management UI.
2. For each queue, create a shovel from the queue on the old instance to the queue on the new instance.
3. Unbind the consumer apps from the old service instance. For instructions, see Unbind a Service Instance From Your App.
4. Bind the consumer apps to the new service instance. For instructions, see Bind a Service Instance to Your App.
5. Restart your consumer apps. For more information, see Restart Your App.

6. Using the Management Web UI, confirm that your consumer apps are successfully connected to the new service instance.

7. Carry out steps 3–5 for your producer apps.

8. Using the Management Web UI, confirm that your producer apps are successfully connected to the new service instance.

9. Ensure all messages are moved from the old instance to the new instance by using its Management Web UI.

10. Verify no messages are in the old instance by checking its Management Web UI.

Migrate Messages by Using Consumers to Drain the Old Service Instance

You can safely migrate messages to the new instance without the use of the shovel plugin. This method is better for ensuring that messages are ordered consistently. However, it requires more manual steps and waiting for queues to be drained.

1. Log in to the RabbitMQ Management Web UI for both the old and new service instances. For instructions about how to do so with or without OAuth enabled, see Using the RabbitMQ Management UI.
2. Unbind the producer apps from the old service instance. For more information, see Unbind a Service Instance From Your App.
3. Bind the producer apps to the new service instance. For more information, see Bind a Service Instance to Your App.
4. Restart your producer apps. For more information, see Restart Your App.

5. Using the Management Web UI, confirm that your producer apps are successfully connected to the new service instance.

6. Wait for the consumer apps to fully drain the queues of the old service instance.

7. Repeat steps 2–4 for your consumer apps.

8. Using the Management Web UI, confirm that your consumer apps are successfully connected to the new service instance.