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