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