c3b3de51a9ece1b3895b25fbbcaa9569b2b37817
[ganeti-github.git] / UPGRADE
1 Upgrade notes
2 =============
3
4 .. highlight:: shell-example
5
6 This document details the steps needed to upgrade a cluster to newer versions
7 of Ganeti.
8
9 As a general rule the node daemons need to be restarted after each software
10 upgrade; if using the provided example init.d script, this means running the
11 following command on all nodes::
12
13     $ /etc/init.d/ganeti restart
14
15
16 2.1 and above
17 -------------
18
19 Starting with Ganeti 2.0, upgrades between revisions (e.g. 2.1.0 to 2.1.1)
20 should not need manual intervention. As a safety measure, minor releases (e.g.
21 2.1.3 to 2.2.0) require the ``cfgupgrade`` command for changing the
22 configuration version. Below you find the steps necessary to upgrade between
23 minor releases.
24
25 To run commands on all nodes, the `distributed shell (dsh)
26 <http://www.netfort.gr.jp/~dancer/software/dsh.html.en>`_ can be used, e.g.
27 ``dsh -M -F 8 -f /var/lib/ganeti/ssconf_online_nodes gnt-cluster --version``.
28
29 #. Ensure no jobs are running (master node only)::
30
31     $ gnt-job list
32
33 #. Pause the watcher for an hour (master node only)::
34
35     $ gnt-cluster watcher pause 1h
36
37 #. Stop all daemons on all nodes::
38
39     $ /etc/init.d/ganeti stop
40
41 #. Backup old configuration (master node only)::
42
43     $ tar czf /var/lib/ganeti-$(date +\%FT\%T).tar.gz -C /var/lib ganeti
44
45 #. Install new Ganeti version on all nodes
46 #. Run cfgupgrade on the master node::
47
48     $ /usr/lib/ganeti/tools/cfgupgrade --verbose --dry-run
49     $ /usr/lib/ganeti/tools/cfgupgrade --verbose
50
51    (``cfgupgrade`` supports a number of parameters, run it with
52    ``--help`` for more information)
53
54 #. Upgrade the directory permissions on all nodes::
55
56     $ /usr/lib/ganeti/ensure-dirs --full-run
57
58 #. Restart daemons on all nodes::
59
60     $ /etc/init.d/ganeti restart
61
62 #. Re-distribute configuration (master node only)::
63
64     $ gnt-cluster redist-conf
65
66 #. Restart daemons again on all nodes::
67
68     $ /etc/init.d/ganeti restart
69
70 #. Enable the watcher again (master node only)::
71
72     $ gnt-cluster watcher continue
73
74 #. Verify cluster (master node only)::
75
76     $ gnt-cluster verify
77
78 Reverting an upgrade
79 ~~~~~~~~~~~~~~~~~~~~
80
81 For going back between revisions (e.g. 2.1.1 to 2.1.0) no manual
82 intervention is required, as for upgrades.
83
84 Starting from version 2.8, ``cfgupgrade`` supports ``--downgrade``
85 option to bring the configuration back to the previous stable version.
86 This is useful if you upgrade Ganeti and after some time you run into
87 problems with the new version. You can downgrade the configuration
88 without losing the changes made since the upgrade. Any feature not
89 supported by the old version will be removed from the configuration, of
90 course, but you get a warning about it. If there is any new feature and
91 you haven't changed from its default value, you don't have to worry
92 about it, as it will get the same value whenever you'll upgrade again.
93
94 The procedure is similar to upgrading, but please notice that you have to
95 revert the configuration **before** installing the old version.
96
97 #. Ensure no jobs are running (master node only)::
98
99     $ gnt-job list
100
101 #. Pause the watcher for an hour (master node only)::
102
103     $ gnt-cluster watcher pause 1h
104
105 #. Stop all daemons on all nodes::
106
107     $ /etc/init.d/ganeti stop
108
109 #. Backup old configuration (master node only)::
110
111     $ tar czf /var/lib/ganeti-$(date +\%FT\%T).tar.gz -C /var/lib ganeti
112
113 #. Run cfgupgrade on the master node::
114
115     $ /usr/lib/ganeti/tools/cfgupgrade --verbose --downgrade --dry-run
116     $ /usr/lib/ganeti/tools/cfgupgrade --verbose --downgrade
117
118    You may want to copy all the messages about features that have been
119    removed during the downgrade, in case you want to restore them when
120    upgrading again.
121
122 #. Install the old Ganeti version on all nodes
123 #. Restart daemons on all nodes::
124
125     $ /etc/init.d/ganeti restart
126
127 #. Re-distribute configuration (master node only)::
128
129     $ gnt-cluster redist-conf
130
131 #. Restart daemons again on all nodes::
132
133     $ /etc/init.d/ganeti restart
134
135 #. Enable the watcher again (master node only)::
136
137     $ gnt-cluster watcher continue
138
139 #. Verify cluster (master node only)::
140
141     $ gnt-cluster verify
142
143
144 2.0 releases
145 ------------
146
147 2.0.3 to 2.0.4
148 ~~~~~~~~~~~~~~
149
150 No changes needed except restarting the daemon; but rollback to 2.0.3 might
151 require configuration editing.
152
153 If you're using Xen-HVM instances, please double-check the network
154 configuration (``nic_type`` parameter) as the defaults might have changed:
155 2.0.4 adds any missing configuration items and depending on the version of the
156 software the cluster has been installed with, some new keys might have been
157 added.
158
159 2.0.1 to 2.0.2/2.0.3
160 ~~~~~~~~~~~~~~~~~~~~
161
162 Between 2.0.1 and 2.0.2 there have been some changes in the handling of block
163 devices, which can cause some issues. 2.0.3 was then released which adds two
164 new options/commands to fix this issue.
165
166 If you use DRBD-type instances and see problems in instance start or
167 activate-disks with messages from DRBD about "lower device too small" or
168 similar, it is recoomended to:
169
170 #. Run ``gnt-instance activate-disks --ignore-size $instance`` for each
171    of the affected instances
172 #. Then run ``gnt-cluster repair-disk-sizes`` which will check that
173    instances have the correct disk sizes
174
175 1.2 to 2.0
176 ----------
177
178 Prerequisites:
179
180 - Ganeti 1.2.7 is currently installed
181 - All instances have been migrated from DRBD 0.7 to DRBD 8.x (i.e. no
182   ``remote_raid1`` disk template)
183 - Upgrade to Ganeti 2.0.0~rc2 or later (~rc1 and earlier don't have the needed
184   upgrade tool)
185
186 In the below steps, replace :file:`/var/lib` with ``$libdir`` if Ganeti was not
187 installed with this prefix (e.g. :file:`/usr/local/var`). Same for
188 :file:`/usr/lib`.
189
190 Execution (all steps are required in the order given):
191
192 #. Make a backup of the current configuration, for safety::
193
194     $ cp -a /var/lib/ganeti /var/lib/ganeti-1.2.backup
195
196 #. Stop all instances::
197
198     $ gnt-instance stop --all
199
200 #. Make sure no DRBD device are in use, the following command should show no
201    active minors::
202
203     $ gnt-cluster command grep cs: /proc/drbd | grep -v cs:Unconf
204
205 #. Stop the node daemons and rapi daemon on all nodes (note: should be logged
206    in not via the cluster name, but the master node name, as the command below
207    will remove the cluster ip from the master node)::
208
209     $ gnt-cluster command /etc/init.d/ganeti stop
210
211 #. Install the new software on all nodes, either from packaging (if available)
212    or from sources; the master daemon will not start but give error messages
213    about wrong configuration file, which is normal
214 #. Upgrade the configuration file::
215
216     $ /usr/lib/ganeti/tools/cfgupgrade12 -v --dry-run
217     $ /usr/lib/ganeti/tools/cfgupgrade12 -v
218
219 #. Make sure ``ganeti-noded`` is running on all nodes (and start it if
220    not)
221 #. Start the master daemon::
222
223     $ ganeti-masterd
224
225 #. Check that a simple node-list works::
226
227     $ gnt-node list
228
229 #. Redistribute updated configuration to all nodes::
230
231     $ gnt-cluster redist-conf
232     $ gnt-cluster copyfile /var/lib/ganeti/known_hosts
233
234 #. Optional: if needed, install RAPI-specific certificates under
235    :file:`/var/lib/ganeti/rapi.pem` and run::
236
237     $ gnt-cluster copyfile /var/lib/ganeti/rapi.pem
238
239 #. Run a cluster verify, this should show no problems::
240
241     $ gnt-cluster verify
242
243 #. Remove some obsolete files::
244
245     $ gnt-cluster command rm /var/lib/ganeti/ssconf_node_pass
246     $ gnt-cluster command rm /var/lib/ganeti/ssconf_hypervisor
247
248 #. Update the xen pvm (if this was a pvm cluster) setting for 1.2
249    compatibility::
250
251     $ gnt-cluster modify -H xen-pvm:root_path=/dev/sda
252
253 #. Depending on your setup, you might also want to reset the initrd parameter::
254
255     $ gnt-cluster modify -H xen-pvm:initrd_path=/boot/initrd-2.6-xenU
256
257 #. Reset the instance autobalance setting to default::
258
259     $ for i in $(gnt-instance list -o name --no-headers); do \
260        gnt-instance modify -B auto_balance=default $i; \
261       done
262
263 #. Optional: start the RAPI demon::
264
265     $ ganeti-rapi
266
267 #. Restart instances::
268
269     $ gnt-instance start --force-multiple --all
270
271 At this point, ``gnt-cluster verify`` should show no errors and the migration
272 is complete.
273
274 1.2 releases
275 ------------
276
277 1.2.4 to any other higher 1.2 version
278 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
279
280 No changes needed. Rollback will usually require manual edit of the
281 configuration file.
282
283 1.2.3 to 1.2.4
284 ~~~~~~~~~~~~~~
285
286 No changes needed. Note that going back from 1.2.4 to 1.2.3 will require manual
287 edit of the configuration file (since we added some HVM-related new
288 attributes).
289
290 1.2.2 to 1.2.3
291 ~~~~~~~~~~~~~~
292
293 No changes needed. Note that the drbd7-to-8 upgrade tool does a disk format
294 change for the DRBD metadata, so in theory this might be **risky**. It is
295 advised to have (good) backups before doing the upgrade.
296
297 1.2.1 to 1.2.2
298 ~~~~~~~~~~~~~~
299
300 No changes needed.
301
302 1.2.0 to 1.2.1
303 ~~~~~~~~~~~~~~
304
305 No changes needed. Only some bugfixes and new additions that don't affect
306 existing clusters.
307
308 1.2.0 beta 3 to 1.2.0
309 ~~~~~~~~~~~~~~~~~~~~~
310
311 No changes needed.
312
313 1.2.0 beta 2 to beta 3
314 ~~~~~~~~~~~~~~~~~~~~~~
315
316 No changes needed. A new version of the debian-etch-instance OS (0.3) has been
317 released, but upgrading it is not required.
318
319 1.2.0 beta 1 to beta 2
320 ~~~~~~~~~~~~~~~~~~~~~~
321
322 Beta 2 switched the config file format to JSON. Steps to upgrade:
323
324 #. Stop the daemons (``/etc/init.d/ganeti stop``) on all nodes
325 #. Disable the cron job (default is :file:`/etc/cron.d/ganeti`)
326 #. Install the new version
327 #. Make a backup copy of the config file
328 #. Upgrade the config file using the following command::
329
330     $ /usr/share/ganeti/cfgupgrade --verbose /var/lib/ganeti/config.data
331
332 #. Start the daemons and run ``gnt-cluster info``, ``gnt-node list`` and
333    ``gnt-instance list`` to check if the upgrade process finished successfully
334
335 The OS definition also need to be upgraded. There is a new version of the
336 debian-etch-instance OS (0.2) that goes along with beta 2.
337
338 .. vim: set textwidth=72 :
339 .. Local Variables:
340 .. mode: rst
341 .. fill-column: 72
342 .. End: