forked from jasonkeene/docs-rabbitmq-staging
-
Notifications
You must be signed in to change notification settings - Fork 0
/
upgrade.html.md.erb
162 lines (127 loc) · 7.71 KB
/
upgrade.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
---
title: Upgrading VMware RabbitMQ for Tanzu Application Service
owner: London Services
---
<%= vars.product_full %> enables automated upgrades between versions of the product.
In some versions, you might be required to take the RabbitMQ cluster offline.
Whenever this is necessary, it is noted in the release notes for those versions.
<%= partial vars.path_to_partials + '/upgrade-planner' %>
This topic applies to both the on-demand and pre-provisioned services.
## <a id="upgrade"></a> Upgrade <%= vars.product_short %>
To upgrade the product:
1. Review the release notes for the version that you are upgrading to.
See [<%= vars.product_short %> Release Notes](releases.html).
1. Download the latest version of the product from [<%= vars.product_network %>](https://network.pivotal.io/products/pivotal-rabbitmq-service).
1. Upload the new .pivotal file to <%= vars.ops_manager %>.
1. If required, upload the stemcell associated with the update.
1. If required, update any new mandatory configuration parameters.
1. Ensure BOSH DNS is enabled. This is enabled by default.
If you have deactivated BOSH DNS, you must activate it for BOSH Hot Swaps to work.
For more information, see [BOSH Hot Swap](#vm-strategy) below.
1. Ensure the `register-on-demand-service-broker` errand is enabled. This errand is enabled by default, but if it has been deactivated, it can be re-activated by navigating to the **Errands** pane and selecting **On** for **Register On Demand Service Broker**.
1. (Optional) If you want developers to individually upgrade service instances, navigate
to the **Errands** pane and select **Off** for **Upgrade All Service Instances**.
<br><br>
By default, the `upgrade-all-service-instances` errand runs after each upgrade.
For more information, see
[About Individual Service Instance Upgrades](#individual-upgrades) below.
1. Click **Review Pending Changes**.
For more information about this <%= vars.ops_manager %> page,
see [Reviewing Pending Product Changes](https://docs.pivotal.io/ops-manager/install/review-pending-changes.html).
1. Click **Apply Changes**.
The rest of the process is automated.
## <a id="general"></a> General Notes About the Upgrade Process
The following notes about the upgrade process apply to upgrading to any version of <%= vars.product_short %>.
* Upgrading to a newer version of the product does not cause any loss of data or
configuration.
* It might take busy RabbitMQ nodes a long time to shut down during
the upgrade and you must not interrupt this process.
* To benefit from rolling upgrades, configure your apps to reconnect after a node restarts.
For more information, see [Handling Node Restarts in Applications](https://www.rabbitmq.com/upgrade.html#rabbitmq-restart-handling)
in the RabbitMQ documentation.
* The benefit you get from stemcell rolling
upgrades depends on how you have configured network partition handling and the
**Resource Config** tab.
An HAProxy instance count of 2 and a RabbitMQ node count of 3 are required for rolling stemcell upgrades.
These counts are the default.
For more information, see [Clustering and Network Partitions](./partitions.html).
* <%= vars.ops_manager %> ensures the instances are updated with the new packages and any
configuration changes are applied automatically
## <a id="general-downtime"></a> Downtime During Upgrades
The length of downtime during upgrades depends on whether there is a stemcell update to
replace the operating system image, or whether the update is for the RabbitMQ software only.
The RabbitMQ cluster becomes unavailable only when upgrading between specific versions of Erlang or RabbitMQ.
This is stated in the release notes for those versions.
For on-demand service instances created with <%= vars.product_short %> v1.20 and later,
stemcell updates no longer incur additional downtime while the IaaS creates the new VM.
For more information, see [BOSH Hot Swap](#vm-strategy) below.
Resilient apps are less likely to crash during downtime.
For how developers can create resilient apps, see the
[resiliency-workloads](https://github.com/rabbitmq/resiliency-workloads) repository in GitHub.
A guide for downtime during upgrade deployments is shown in the table below.
In some cases, the RabbitMQ cluster remains available during a tile upgrade,
but individual queues on cluster nodes might be taken offline.
<p class="note warning">
<strong>Warning:</strong> The following table is only a guide.
Always read the release notes for the version you are upgrading to.
</p>
<table border="1" class="nice">
<tr>
<th>Upgrade Type</th>
<th>Will Downtime Be Required For This Upgrade or Update? </th>
</tr>
<tr>
<th>Major Tile Version</th>
<td>See the release notes for that version.
</td>
</tr>
<tr>
<th>Minor Tile Version</th>
<td><strong>For 1.17.2 and earlier:</strong> The RabbitMQ cluster is taken offline for the duration of the upgrade.<br>
<strong>For 1.17.3 and later:</strong> Normally these are rolling deployments with each node being updated in turn.
In these cases, the cluster remains available, but individual queues might be taken offline as each node is restarted.
There might be specific migration paths that require downtime. These are identified in the release notes for that version.
</td>
</tr>
<tr>
<th>Patch Tile Version</th>
<td>Normally these are rolling deployments with each node being updated in turn.
In these cases the cluster remains available, but individual queues might be taken offline as each node is restarted.
There might be specific migration paths that require downtime. These are identified in the release notes for that version.
</td>
<tr>
<th>Stemcell-Only Patch Tile Version</th>
<td>Where the patch update is only a new stemcell version these are rolling deployments with each node being updated in turn.
In these cases the cluster remains available, but individual queues might be taken offline as each node is restarted.
</td>
</tr>
</table>
### <a id="vm-strategy"></a> BOSH Hot Swap
On-demand service instances created using <%= vars.product_short %> v1.20 and later use the
`vm_strategy` `create-swap-delete`.
This significantly reduces downtime because VM creation and deletion does not affect the downtime
of a RabbitMQ node being updated.
Depending on your IaaS, VM creation and deletion can take between a few seconds and several minutes.
Your IaaS resource usage surges during the deployment while BOSH creates additional VMs in preparation
for the update.
You might need to review resource limits for your IaaS and account.
If your limits are too low, your deployment fails.
To use this feature, you must have BOSH DNS enabled.
For more information about `create-swap-delete`, see
[Changing VM Update Strategy](https://bosh.io/docs/changing-deployment-vm-strategy/)
in the BOSH documentation.
<p class="note">
<strong>Note:</strong> On-demand service instances created using <%= vars.product_short %> v1.19 or earlier
and upgraded to v1.20 or later continue to use the <code>vm_strategy</code> <code>delete-create</code>.
</p>
### <a id="individual-upgrades"></a> About Individual Service Instance Upgrades
<%= partial vars.path_to_partials + "/services/devs-can-upgrade-one-si" %>
## <a id="policy"></a> Release Policy
<%# The below partial is in https://github.com/pivotal-cf/docs-partials %>
<%= partial vars.path_to_partials + '/services/release-policy', :locals => {
:os_name => "RabbitMQ"
} %>
The <%= vars.product_short %> tile uses floating stemcells in v1.14.0 and later.
This means that the tile can be updated to use the latest minor version of a stemcell,
without the need to download a new <%= vars.product_short %> patch release from Pivnet.
For more information see [Floating Stemcells](https://docs.pivotal.io/ops-manager/install/understanding-stemcells.html).