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:
Create a new service instance. VMware recommends using the on-demand service for new deployments. For instructions, see Create a Service Instance.
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.
Migrate policies and parameters. For instructions, see Migrate Policies and Parameters below.
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.
When ready, delete your old instance. For instructions, see Delete a Service Instance.
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.
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 instanceSERVICE-KEY
is a name of your choice for your service key
Retrieve the admin username and password with the following command:
cf service-key SERVICE-INSTANCE SERVICE-KEY
Where:
SERVICE-INSTANCE
is your service instanceSERVICE-KEY
is the service key name you chose in the step above
Retrieve the URL of the new service instance with the following command:
cf service SERVICE-INSTANCE
Where
SERVICE-INSTANCE
is your service instance.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 clusterPASSWORD
is the admin password for the clusterOLD-MANAGEMENT-URL
is the RabbitMQ Management UI URL for your old service instanceVHOST
is your virtual host ID
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 clusterPASSWORD
is the admin password for the clusterNEW-MANAGEMENT-URL
is the RabbitMQ Management UI URL for your new service instanceVHOST
is your virtual host ID
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
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.
- 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.
- For each queue, create a shovel from the queue on the old instance to the queue on the new instance.
- Unbind the consumer apps from the old service instance. For instructions, see Unbind a Service Instance From Your App.
- Bind the consumer apps to the new service instance. For instructions, see Bind a Service Instance to Your App.
- Restart your consumer apps. For more information, see Restart Your App.
Using the Management Web UI, confirm that your consumer apps are successfully connected to the new service instance.
Carry out steps 3–5 for your producer apps.
Using the Management Web UI, confirm that your producer apps are successfully connected to the new service instance.
Ensure all messages are moved from the old instance to the new instance by using its Management Web UI.
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.
- 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.
- Unbind the producer apps from the old service instance. For more information, see Unbind a Service Instance From Your App.
- Bind the producer apps to the new service instance. For more information, see Bind a Service Instance to Your App.
- Restart your producer apps. For more information, see Restart Your App.
Using the Management Web UI, confirm that your producer apps are successfully connected to the new service instance.
Wait for the consumer apps to fully drain the queues of the old service instance.
Repeat steps 2–4 for your consumer apps.
Using the Management Web UI, confirm that your consumer apps are successfully connected to the new service instance.