18efd65ac0ab08eaf40d781600b6483c46ffdcbf
[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 2.11 and above
16 --------------
17
18 Starting from 2.10 onwards, Ganeti has support for parallely installed versions
19 and automated upgrades. The default configuration for 2.11 and higher already is
20 to install as a parallel version without changing the running version. If both
21 versions, the installed one and the one to upgrade to, are 2.10 or higher, the
22 actual switch of the live version can be carried out by the following command
23 on the master node.::
24
25    $ gnt-cluster upgrade --to 2.11
26
27 This will carry out the steps described below in the section on upgrades from
28 2.1 and above. Downgrades to the previous minor version can be done in the same
29 way, specifiying the smaller version on the ``--to`` argument.
30
31 Note that ``gnt-cluster upgrade`` only manages the actual switch between
32 versions as described below on upgrades from 2.1 and above. It does not install
33 or remove any binaries. Having the new binaries installed is a prerequisite of
34 calling ``gnt-cluster upgrade`` (and the command will abort if the prerequisite
35 is not met). The old binaries can be used to downgrade back to the previous
36 version; once the system administrator decides that going back to the old
37 version is not needed any more, they can be removed. Addition and removal of
38 the Ganeti binaries should happen in the same way as for all other binaries on
39 your system.
40
41
42 2.13
43 ----
44
45 When upgrading to 2.13, first apply the instructions of ``2.11 and
46 above``. 2.13 comes with the new feature of enhanced SSH security
47 through individual SSH keys. This features needs to be enabled
48 after the upgrade by::
49
50    $ gnt-cluster renew-crypto --new-ssh-keys --no-ssh-key-check
51
52 Note that new SSH keys are generated automatically without warning when
53 upgrading with ``gnt-cluster upgrade``.
54
55 If you instructed Ganeti to not touch the SSH setup (by using the
56 ``--no-ssh-init`` option of ``gnt-cluster init``, the changes in the
57 handling of SSH keys will not affect your cluster.
58
59 If you want to be prompted for each newly created SSH key, leave out
60 the ``--no-ssh-key-check`` option in the command listed above.
61
62 Note that after a downgrade from 2.13 to 2.12, the individual SSH keys
63 will not get removed automatically. This can lead to reachability
64 errors under very specific circumstances (Issue 1008). In case you plan
65 on keeping 2.12 for a while and not upgrade to 2.13 again soon, we recommend
66 to replace all SSH key pairs of non-master nodes' with the master node's SSH
67 key pair.
68
69
70 2.12
71 ----
72
73 Due to issue #1094 in Ganeti 2.11 and 2.12 up to version 2.12.4, we
74 advise to rerun 'gnt-cluster renew-crypto --new-node-certificates'
75 after an upgrade to 2.12.5 or higher.
76
77
78 2.11
79 ----
80
81 When upgrading to 2.11, first apply the instructions of ``2.11 and
82 above``. 2.11 comes with the new feature of enhanced RPC security
83 through client certificates. This features needs to be enabled after the
84 upgrade by::
85
86    $ gnt-cluster renew-crypto --new-node-certificates
87
88 Note that new node certificates are generated automatically without
89 warning when upgrading with ``gnt-cluster upgrade``.
90
91
92 2.1 and above
93 -------------
94
95 Starting with Ganeti 2.0, upgrades between revisions (e.g. 2.1.0 to 2.1.1)
96 should not need manual intervention. As a safety measure, minor releases (e.g.
97 2.1.3 to 2.2.0) require the ``cfgupgrade`` command for changing the
98 configuration version. Below you find the steps necessary to upgrade between
99 minor releases.
100
101 To run commands on all nodes, the `distributed shell (dsh)
102 <http://www.netfort.gr.jp/~dancer/software/dsh.html.en>`_ can be used, e.g.
103 ``dsh -M -F 8 -f /var/lib/ganeti/ssconf_online_nodes gnt-cluster --version``.
104
105 #. Ensure no jobs are running (master node only)::
106
107     $ gnt-job list
108
109 #. Pause the watcher for an hour (master node only)::
110
111     $ gnt-cluster watcher pause 1h
112
113 #. Stop all daemons on all nodes::
114
115     $ /etc/init.d/ganeti stop
116
117 #. Backup old configuration (master node only)::
118
119     $ tar czf /var/lib/ganeti-$(date +\%FT\%T).tar.gz -C /var/lib ganeti
120
121     (``/var/lib/ganeti`` can also contain exported instances, so make sure to
122     backup only files you are interested in. Use ``--exclude export`` for
123     example)
124
125 #. Install new Ganeti version on all nodes
126 #. Run cfgupgrade on the master node::
127
128     $ /usr/lib/ganeti/tools/cfgupgrade --verbose --dry-run
129     $ /usr/lib/ganeti/tools/cfgupgrade --verbose
130
131    (``cfgupgrade`` supports a number of parameters, run it with
132    ``--help`` for more information)
133
134 #. Upgrade the directory permissions on all nodes::
135
136     $ /usr/lib/ganeti/ensure-dirs --full-run
137
138 #. Create the (missing) required users and make users part of the required
139    groups on all nodes::
140
141     $ /usr/lib/ganeti/tools/users-setup
142
143    This will ask for confirmation. To execute directly, add the ``--yes-do-it``
144    option.
145
146 #. Restart daemons on all nodes::
147
148     $ /etc/init.d/ganeti restart
149
150 #. Re-distribute configuration (master node only)::
151
152     $ gnt-cluster redist-conf
153
154 #. If you use file storage, check that the ``/etc/ganeti/file-storage-paths``
155    is correct on all nodes. For security reasons it's not copied
156    automatically, but it can be copied manually via::
157
158    $ gnt-cluster copyfile /etc/ganeti/file-storage-paths
159
160 #. Restart daemons again on all nodes::
161
162     $ /etc/init.d/ganeti restart
163
164 #. Enable the watcher again (master node only)::
165
166     $ gnt-cluster watcher continue
167
168 #. Verify cluster (master node only)::
169
170     $ gnt-cluster verify
171
172 Reverting an upgrade
173 ~~~~~~~~~~~~~~~~~~~~
174
175 For going back between revisions (e.g. 2.1.1 to 2.1.0) no manual
176 intervention is required, as for upgrades.
177
178 Starting from version 2.8, ``cfgupgrade`` supports ``--downgrade``
179 option to bring the configuration back to the previous stable version.
180 This is useful if you upgrade Ganeti and after some time you run into
181 problems with the new version. You can downgrade the configuration
182 without losing the changes made since the upgrade. Any feature not
183 supported by the old version will be removed from the configuration, of
184 course, but you get a warning about it. If there is any new feature and
185 you haven't changed from its default value, you don't have to worry
186 about it, as it will get the same value whenever you'll upgrade again.
187
188 Automatic downgrades
189 ....................
190
191 From version 2.11 onwards, downgrades can be done by using the
192 ``gnt-cluster upgrade`` command.::
193
194   gnt-cluster upgrade --to 2.10
195
196 Manual downgrades
197 .................
198
199 The procedure is similar to upgrading, but please notice that you have to
200 revert the configuration **before** installing the old version.
201
202 #. Ensure no jobs are running (master node only)::
203
204     $ gnt-job list
205
206 #. Pause the watcher for an hour (master node only)::
207
208     $ gnt-cluster watcher pause 1h
209
210 #. Stop all daemons on all nodes::
211
212     $ /etc/init.d/ganeti stop
213
214 #. Backup old configuration (master node only)::
215
216     $ tar czf /var/lib/ganeti-$(date +\%FT\%T).tar.gz -C /var/lib ganeti
217
218 #. Run cfgupgrade on the master node::
219
220     $ /usr/lib/ganeti/tools/cfgupgrade --verbose --downgrade --dry-run
221     $ /usr/lib/ganeti/tools/cfgupgrade --verbose --downgrade
222
223    You may want to copy all the messages about features that have been
224    removed during the downgrade, in case you want to restore them when
225    upgrading again.
226
227 #. Install the old Ganeti version on all nodes
228
229    NB: in Ganeti 2.8, the ``cmdlib.py`` file was split into a series of files
230    contained in the ``cmdlib`` directory. If Ganeti is installed from sources
231    and not from a package, while downgrading Ganeti to a pre-2.8
232    version it is important to remember to remove the ``cmdlib`` directory
233    from the directory containing the Ganeti python files (which usually is
234    ``${PREFIX}/lib/python${VERSION}/dist-packages/ganeti``).
235    A simpler upgrade/downgrade procedure will be made available in future
236    versions of Ganeti.
237
238 #. Restart daemons on all nodes::
239
240     $ /etc/init.d/ganeti restart
241
242 #. Re-distribute configuration (master node only)::
243
244     $ gnt-cluster redist-conf
245
246 #. Restart daemons again on all nodes::
247
248     $ /etc/init.d/ganeti restart
249
250 #. Enable the watcher again (master node only)::
251
252     $ gnt-cluster watcher continue
253
254 #. Verify cluster (master node only)::
255
256     $ gnt-cluster verify
257
258 Specific tasks for 2.11 to 2.10 downgrade
259 ,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,
260
261 After running ``cfgupgrade``, the ``client.pem`` and
262 ``ssconf_master_candidates_certs`` files need to be removed
263 from Ganeti's data directory on all nodes. While this step is
264 not necessary for 2.10 to run cleanly, leaving them will cause
265 problems when upgrading again after the downgrade.
266
267 2.0 releases
268 ------------
269
270 2.0.3 to 2.0.4
271 ~~~~~~~~~~~~~~
272
273 No changes needed except restarting the daemon; but rollback to 2.0.3 might
274 require configuration editing.
275
276 If you're using Xen-HVM instances, please double-check the network
277 configuration (``nic_type`` parameter) as the defaults might have changed:
278 2.0.4 adds any missing configuration items and depending on the version of the
279 software the cluster has been installed with, some new keys might have been
280 added.
281
282 2.0.1 to 2.0.2/2.0.3
283 ~~~~~~~~~~~~~~~~~~~~
284
285 Between 2.0.1 and 2.0.2 there have been some changes in the handling of block
286 devices, which can cause some issues. 2.0.3 was then released which adds two
287 new options/commands to fix this issue.
288
289 If you use DRBD-type instances and see problems in instance start or
290 activate-disks with messages from DRBD about "lower device too small" or
291 similar, it is recoomended to:
292
293 #. Run ``gnt-instance activate-disks --ignore-size $instance`` for each
294    of the affected instances
295 #. Then run ``gnt-cluster repair-disk-sizes`` which will check that
296    instances have the correct disk sizes
297
298 1.2 to 2.0
299 ----------
300
301 Prerequisites:
302
303 - Ganeti 1.2.7 is currently installed
304 - All instances have been migrated from DRBD 0.7 to DRBD 8.x (i.e. no
305   ``remote_raid1`` disk template)
306 - Upgrade to Ganeti 2.0.0~rc2 or later (~rc1 and earlier don't have the needed
307   upgrade tool)
308
309 In the below steps, replace :file:`/var/lib` with ``$libdir`` if Ganeti was not
310 installed with this prefix (e.g. :file:`/usr/local/var`). Same for
311 :file:`/usr/lib`.
312
313 Execution (all steps are required in the order given):
314
315 #. Make a backup of the current configuration, for safety::
316
317     $ cp -a /var/lib/ganeti /var/lib/ganeti-1.2.backup
318
319 #. Stop all instances::
320
321     $ gnt-instance stop --all
322
323 #. Make sure no DRBD device are in use, the following command should show no
324    active minors::
325
326     $ gnt-cluster command grep cs: /proc/drbd | grep -v cs:Unconf
327
328 #. Stop the node daemons and rapi daemon on all nodes (note: should be logged
329    in not via the cluster name, but the master node name, as the command below
330    will remove the cluster ip from the master node)::
331
332     $ gnt-cluster command /etc/init.d/ganeti stop
333
334 #. Install the new software on all nodes, either from packaging (if available)
335    or from sources; the master daemon will not start but give error messages
336    about wrong configuration file, which is normal
337 #. Upgrade the configuration file::
338
339     $ /usr/lib/ganeti/tools/cfgupgrade12 -v --dry-run
340     $ /usr/lib/ganeti/tools/cfgupgrade12 -v
341
342 #. Make sure ``ganeti-noded`` is running on all nodes (and start it if
343    not)
344 #. Start the master daemon::
345
346     $ ganeti-masterd
347
348 #. Check that a simple node-list works::
349
350     $ gnt-node list
351
352 #. Redistribute updated configuration to all nodes::
353
354     $ gnt-cluster redist-conf
355     $ gnt-cluster copyfile /var/lib/ganeti/known_hosts
356
357 #. Optional: if needed, install RAPI-specific certificates under
358    :file:`/var/lib/ganeti/rapi.pem` and run::
359
360     $ gnt-cluster copyfile /var/lib/ganeti/rapi.pem
361
362 #. Run a cluster verify, this should show no problems::
363
364     $ gnt-cluster verify
365
366 #. Remove some obsolete files::
367
368     $ gnt-cluster command rm /var/lib/ganeti/ssconf_node_pass
369     $ gnt-cluster command rm /var/lib/ganeti/ssconf_hypervisor
370
371 #. Update the xen pvm (if this was a pvm cluster) setting for 1.2
372    compatibility::
373
374     $ gnt-cluster modify -H xen-pvm:root_path=/dev/sda
375
376 #. Depending on your setup, you might also want to reset the initrd parameter::
377
378     $ gnt-cluster modify -H xen-pvm:initrd_path=/boot/initrd-2.6-xenU
379
380 #. Reset the instance autobalance setting to default::
381
382     $ for i in $(gnt-instance list -o name --no-headers); do \
383        gnt-instance modify -B auto_balance=default $i; \
384       done
385
386 #. Optional: start the RAPI demon::
387
388     $ ganeti-rapi
389
390 #. Restart instances::
391
392     $ gnt-instance start --force-multiple --all
393
394 At this point, ``gnt-cluster verify`` should show no errors and the migration
395 is complete.
396
397 1.2 releases
398 ------------
399
400 1.2.4 to any other higher 1.2 version
401 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
402
403 No changes needed. Rollback will usually require manual edit of the
404 configuration file.
405
406 1.2.3 to 1.2.4
407 ~~~~~~~~~~~~~~
408
409 No changes needed. Note that going back from 1.2.4 to 1.2.3 will require manual
410 edit of the configuration file (since we added some HVM-related new
411 attributes).
412
413 1.2.2 to 1.2.3
414 ~~~~~~~~~~~~~~
415
416 No changes needed. Note that the drbd7-to-8 upgrade tool does a disk format
417 change for the DRBD metadata, so in theory this might be **risky**. It is
418 advised to have (good) backups before doing the upgrade.
419
420 1.2.1 to 1.2.2
421 ~~~~~~~~~~~~~~
422
423 No changes needed.
424
425 1.2.0 to 1.2.1
426 ~~~~~~~~~~~~~~
427
428 No changes needed. Only some bugfixes and new additions that don't affect
429 existing clusters.
430
431 1.2.0 beta 3 to 1.2.0
432 ~~~~~~~~~~~~~~~~~~~~~
433
434 No changes needed.
435
436 1.2.0 beta 2 to beta 3
437 ~~~~~~~~~~~~~~~~~~~~~~
438
439 No changes needed. A new version of the debian-etch-instance OS (0.3) has been
440 released, but upgrading it is not required.
441
442 1.2.0 beta 1 to beta 2
443 ~~~~~~~~~~~~~~~~~~~~~~
444
445 Beta 2 switched the config file format to JSON. Steps to upgrade:
446
447 #. Stop the daemons (``/etc/init.d/ganeti stop``) on all nodes
448 #. Disable the cron job (default is :file:`/etc/cron.d/ganeti`)
449 #. Install the new version
450 #. Make a backup copy of the config file
451 #. Upgrade the config file using the following command::
452
453     $ /usr/share/ganeti/cfgupgrade --verbose /var/lib/ganeti/config.data
454
455 #. Start the daemons and run ``gnt-cluster info``, ``gnt-node list`` and
456    ``gnt-instance list`` to check if the upgrade process finished successfully
457
458 The OS definition also need to be upgraded. There is a new version of the
459 debian-etch-instance OS (0.2) that goes along with beta 2.
460
461 .. vim: set textwidth=72 :
462 .. Local Variables:
463 .. mode: rst
464 .. fill-column: 72
465 .. End: