Mention manual creation of {shared,}file paths in UPGRADE
[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    Note that ensure-dirs does not create the directories for file
139    and shared-file storage. This is due to security reasons. They need
140    to be created manually. For details see ``man gnt-cluster``. 
141
142 #. Create the (missing) required users and make users part of the required
143    groups on all nodes::
144
145     $ /usr/lib/ganeti/tools/users-setup
146
147    This will ask for confirmation. To execute directly, add the ``--yes-do-it``
148    option.
149
150 #. Restart daemons on all nodes::
151
152     $ /etc/init.d/ganeti restart
153
154 #. Re-distribute configuration (master node only)::
155
156     $ gnt-cluster redist-conf
157
158 #. If you use file storage, check that the ``/etc/ganeti/file-storage-paths``
159    is correct on all nodes. For security reasons it's not copied
160    automatically, but it can be copied manually via::
161
162    $ gnt-cluster copyfile /etc/ganeti/file-storage-paths
163
164 #. Restart daemons again on all nodes::
165
166     $ /etc/init.d/ganeti restart
167
168 #. Enable the watcher again (master node only)::
169
170     $ gnt-cluster watcher continue
171
172 #. Verify cluster (master node only)::
173
174     $ gnt-cluster verify
175
176 Reverting an upgrade
177 ~~~~~~~~~~~~~~~~~~~~
178
179 For going back between revisions (e.g. 2.1.1 to 2.1.0) no manual
180 intervention is required, as for upgrades.
181
182 Starting from version 2.8, ``cfgupgrade`` supports ``--downgrade``
183 option to bring the configuration back to the previous stable version.
184 This is useful if you upgrade Ganeti and after some time you run into
185 problems with the new version. You can downgrade the configuration
186 without losing the changes made since the upgrade. Any feature not
187 supported by the old version will be removed from the configuration, of
188 course, but you get a warning about it. If there is any new feature and
189 you haven't changed from its default value, you don't have to worry
190 about it, as it will get the same value whenever you'll upgrade again.
191
192 Automatic downgrades
193 ....................
194
195 From version 2.11 onwards, downgrades can be done by using the
196 ``gnt-cluster upgrade`` command.::
197
198   gnt-cluster upgrade --to 2.10
199
200 Manual downgrades
201 .................
202
203 The procedure is similar to upgrading, but please notice that you have to
204 revert the configuration **before** installing the old version.
205
206 #. Ensure no jobs are running (master node only)::
207
208     $ gnt-job list
209
210 #. Pause the watcher for an hour (master node only)::
211
212     $ gnt-cluster watcher pause 1h
213
214 #. Stop all daemons on all nodes::
215
216     $ /etc/init.d/ganeti stop
217
218 #. Backup old configuration (master node only)::
219
220     $ tar czf /var/lib/ganeti-$(date +\%FT\%T).tar.gz -C /var/lib ganeti
221
222 #. Run cfgupgrade on the master node::
223
224     $ /usr/lib/ganeti/tools/cfgupgrade --verbose --downgrade --dry-run
225     $ /usr/lib/ganeti/tools/cfgupgrade --verbose --downgrade
226
227    You may want to copy all the messages about features that have been
228    removed during the downgrade, in case you want to restore them when
229    upgrading again.
230
231 #. Install the old Ganeti version on all nodes
232
233    NB: in Ganeti 2.8, the ``cmdlib.py`` file was split into a series of files
234    contained in the ``cmdlib`` directory. If Ganeti is installed from sources
235    and not from a package, while downgrading Ganeti to a pre-2.8
236    version it is important to remember to remove the ``cmdlib`` directory
237    from the directory containing the Ganeti python files (which usually is
238    ``${PREFIX}/lib/python${VERSION}/dist-packages/ganeti``).
239    A simpler upgrade/downgrade procedure will be made available in future
240    versions of Ganeti.
241
242 #. Restart daemons on all nodes::
243
244     $ /etc/init.d/ganeti restart
245
246 #. Re-distribute configuration (master node only)::
247
248     $ gnt-cluster redist-conf
249
250 #. Restart daemons again on all nodes::
251
252     $ /etc/init.d/ganeti restart
253
254 #. Enable the watcher again (master node only)::
255
256     $ gnt-cluster watcher continue
257
258 #. Verify cluster (master node only)::
259
260     $ gnt-cluster verify
261
262 Specific tasks for 2.11 to 2.10 downgrade
263 ,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,
264
265 After running ``cfgupgrade``, the ``client.pem`` and
266 ``ssconf_master_candidates_certs`` files need to be removed
267 from Ganeti's data directory on all nodes. While this step is
268 not necessary for 2.10 to run cleanly, leaving them will cause
269 problems when upgrading again after the downgrade.
270
271 2.0 releases
272 ------------
273
274 2.0.3 to 2.0.4
275 ~~~~~~~~~~~~~~
276
277 No changes needed except restarting the daemon; but rollback to 2.0.3 might
278 require configuration editing.
279
280 If you're using Xen-HVM instances, please double-check the network
281 configuration (``nic_type`` parameter) as the defaults might have changed:
282 2.0.4 adds any missing configuration items and depending on the version of the
283 software the cluster has been installed with, some new keys might have been
284 added.
285
286 2.0.1 to 2.0.2/2.0.3
287 ~~~~~~~~~~~~~~~~~~~~
288
289 Between 2.0.1 and 2.0.2 there have been some changes in the handling of block
290 devices, which can cause some issues. 2.0.3 was then released which adds two
291 new options/commands to fix this issue.
292
293 If you use DRBD-type instances and see problems in instance start or
294 activate-disks with messages from DRBD about "lower device too small" or
295 similar, it is recoomended to:
296
297 #. Run ``gnt-instance activate-disks --ignore-size $instance`` for each
298    of the affected instances
299 #. Then run ``gnt-cluster repair-disk-sizes`` which will check that
300    instances have the correct disk sizes
301
302 1.2 to 2.0
303 ----------
304
305 Prerequisites:
306
307 - Ganeti 1.2.7 is currently installed
308 - All instances have been migrated from DRBD 0.7 to DRBD 8.x (i.e. no
309   ``remote_raid1`` disk template)
310 - Upgrade to Ganeti 2.0.0~rc2 or later (~rc1 and earlier don't have the needed
311   upgrade tool)
312
313 In the below steps, replace :file:`/var/lib` with ``$libdir`` if Ganeti was not
314 installed with this prefix (e.g. :file:`/usr/local/var`). Same for
315 :file:`/usr/lib`.
316
317 Execution (all steps are required in the order given):
318
319 #. Make a backup of the current configuration, for safety::
320
321     $ cp -a /var/lib/ganeti /var/lib/ganeti-1.2.backup
322
323 #. Stop all instances::
324
325     $ gnt-instance stop --all
326
327 #. Make sure no DRBD device are in use, the following command should show no
328    active minors::
329
330     $ gnt-cluster command grep cs: /proc/drbd | grep -v cs:Unconf
331
332 #. Stop the node daemons and rapi daemon on all nodes (note: should be logged
333    in not via the cluster name, but the master node name, as the command below
334    will remove the cluster ip from the master node)::
335
336     $ gnt-cluster command /etc/init.d/ganeti stop
337
338 #. Install the new software on all nodes, either from packaging (if available)
339    or from sources; the master daemon will not start but give error messages
340    about wrong configuration file, which is normal
341 #. Upgrade the configuration file::
342
343     $ /usr/lib/ganeti/tools/cfgupgrade12 -v --dry-run
344     $ /usr/lib/ganeti/tools/cfgupgrade12 -v
345
346 #. Make sure ``ganeti-noded`` is running on all nodes (and start it if
347    not)
348 #. Start the master daemon::
349
350     $ ganeti-masterd
351
352 #. Check that a simple node-list works::
353
354     $ gnt-node list
355
356 #. Redistribute updated configuration to all nodes::
357
358     $ gnt-cluster redist-conf
359     $ gnt-cluster copyfile /var/lib/ganeti/known_hosts
360
361 #. Optional: if needed, install RAPI-specific certificates under
362    :file:`/var/lib/ganeti/rapi.pem` and run::
363
364     $ gnt-cluster copyfile /var/lib/ganeti/rapi.pem
365
366 #. Run a cluster verify, this should show no problems::
367
368     $ gnt-cluster verify
369
370 #. Remove some obsolete files::
371
372     $ gnt-cluster command rm /var/lib/ganeti/ssconf_node_pass
373     $ gnt-cluster command rm /var/lib/ganeti/ssconf_hypervisor
374
375 #. Update the xen pvm (if this was a pvm cluster) setting for 1.2
376    compatibility::
377
378     $ gnt-cluster modify -H xen-pvm:root_path=/dev/sda
379
380 #. Depending on your setup, you might also want to reset the initrd parameter::
381
382     $ gnt-cluster modify -H xen-pvm:initrd_path=/boot/initrd-2.6-xenU
383
384 #. Reset the instance autobalance setting to default::
385
386     $ for i in $(gnt-instance list -o name --no-headers); do \
387        gnt-instance modify -B auto_balance=default $i; \
388       done
389
390 #. Optional: start the RAPI demon::
391
392     $ ganeti-rapi
393
394 #. Restart instances::
395
396     $ gnt-instance start --force-multiple --all
397
398 At this point, ``gnt-cluster verify`` should show no errors and the migration
399 is complete.
400
401 1.2 releases
402 ------------
403
404 1.2.4 to any other higher 1.2 version
405 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
406
407 No changes needed. Rollback will usually require manual edit of the
408 configuration file.
409
410 1.2.3 to 1.2.4
411 ~~~~~~~~~~~~~~
412
413 No changes needed. Note that going back from 1.2.4 to 1.2.3 will require manual
414 edit of the configuration file (since we added some HVM-related new
415 attributes).
416
417 1.2.2 to 1.2.3
418 ~~~~~~~~~~~~~~
419
420 No changes needed. Note that the drbd7-to-8 upgrade tool does a disk format
421 change for the DRBD metadata, so in theory this might be **risky**. It is
422 advised to have (good) backups before doing the upgrade.
423
424 1.2.1 to 1.2.2
425 ~~~~~~~~~~~~~~
426
427 No changes needed.
428
429 1.2.0 to 1.2.1
430 ~~~~~~~~~~~~~~
431
432 No changes needed. Only some bugfixes and new additions that don't affect
433 existing clusters.
434
435 1.2.0 beta 3 to 1.2.0
436 ~~~~~~~~~~~~~~~~~~~~~
437
438 No changes needed.
439
440 1.2.0 beta 2 to beta 3
441 ~~~~~~~~~~~~~~~~~~~~~~
442
443 No changes needed. A new version of the debian-etch-instance OS (0.3) has been
444 released, but upgrading it is not required.
445
446 1.2.0 beta 1 to beta 2
447 ~~~~~~~~~~~~~~~~~~~~~~
448
449 Beta 2 switched the config file format to JSON. Steps to upgrade:
450
451 #. Stop the daemons (``/etc/init.d/ganeti stop``) on all nodes
452 #. Disable the cron job (default is :file:`/etc/cron.d/ganeti`)
453 #. Install the new version
454 #. Make a backup copy of the config file
455 #. Upgrade the config file using the following command::
456
457     $ /usr/share/ganeti/cfgupgrade --verbose /var/lib/ganeti/config.data
458
459 #. Start the daemons and run ``gnt-cluster info``, ``gnt-node list`` and
460    ``gnt-instance list`` to check if the upgrade process finished successfully
461
462 The OS definition also need to be upgraded. There is a new version of the
463 debian-etch-instance OS (0.2) that goes along with beta 2.
464
465 .. vim: set textwidth=72 :
466 .. Local Variables:
467 .. mode: rst
468 .. fill-column: 72
469 .. End: