forked from jasonkeene/docs-rabbitmq-staging
-
Notifications
You must be signed in to change notification settings - Fork 0
/
migration.html.md.erb
169 lines (119 loc) · 7.4 KB
/
migration.html.md.erb
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
---
title: Migrating a VMware RabbitMQ for Tanzu Application Service Service Instance to Another Service Instance
owner: London Services
---
This topic describes how to safely and fully migrate a <%= vars.product_short %> service instance to
another service instance.
This migration can include migrating policies, parameters, and messages.
## <a id="migrate-instance"></a> Migrate a <%= vars.product_short %> 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](./use.html#create).
1. 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.
1. Migrate policies and parameters.
For instructions, see [Migrate Policies and Parameters](#policies-and-params) below.
1. If you need all the messages in the old service instance, migrate the messages in the queues.
For instructions, see [Migrate Messages in Queues](#messages) below.
1. When ready, delete your old instance.
For instructions, see [Delete a Service Instance](./use.html#delete).
1. If you have service-keys for the old instance, create service-keys for
the new instance and replace the old credentials.
## <a id="policies-and-params"></a> 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`
You can apply them using the API by following the steps below.
<p class="note">
<strong>Note:</strong> You can also apply them in the RabbitMQ Management UI.
The API is the faster option if you have multiple instances to migrate.
</p>
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
1. 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
1. Retrieve the URL of the new service instance with the following command:
```
cf service SERVICE-INSTANCE
```
Where `SERVICE-INSTANCE` is your service instance.
1. 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
1. 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
1. 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
```
1. 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)"
```
## <a id="messages"></a> 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](#messages-shovel)
* [Migrate Messages By Using Consumers to Drain the Old Service Instance](#messages-consumers)
Use of the shovel plugin requires less waiting time and manual steps, however, it does not preserve the
ordering of messages.
### <a id="messages-shovel"></a> 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](https://www.rabbitmq.com/shovel.html).
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](./managing.html).
1. For each queue, create a shovel from the queue on the old instance to the queue on the new instance.
1. Unbind the consumer apps from the old service instance.
For instructions, see [Unbind a Service Instance From Your App](./use.html#unbind).
1. Bind the consumer apps to the new service instance.
For instructions, see [Bind a Service Instance to Your App](./use.html#bind).
1. Restart your consumer apps.
For more information, see [Restart Your App](https://docs.pivotal.io/application-service/devguide/deploy-apps/start-restart-restage.html#restart).
1. Using the Management Web UI, confirm that your consumer apps are successfully connected to the new service instance.
1. Carry out steps 3--5 for your producer apps.
1. Using the Management Web UI, confirm that your producer apps are successfully connected to the new service instance.
1. Ensure all messages are moved from the old instance to the new instance by using its Management Web UI.
1. Verify no messages are in the old instance by checking its Management Web UI.
### <a id="messages-consumers"></a> 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](./managing.html).
1. Unbind the producer apps from the old service instance.
For more information, see [Unbind a Service Instance From Your App](./use.html#unbind).
1. Bind the producer apps to the new service instance.
For more information, see [Bind a Service Instance to Your App](./use.html#bind).
1. Restart your producer apps.
For more information, see [Restart Your App](https://docs.pivotal.io/application-service/devguide/deploy-apps/start-restart-restage.html#restart).
1. Using the Management Web UI, confirm that your producer apps are successfully connected to the new service instance.
1. Wait for the consumer apps to fully drain the queues of the old service instance.
1. Repeat steps 2--4 for your consumer apps.
1. Using the Management Web UI, confirm that your consumer apps are successfully connected to the new service instance.