02157d537fa909d7f2008829be033cd22f588c1b
[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 #. Restart daemons on all nodes::
55
56     $ /etc/init.d/ganeti restart
57
58 #. Re-distribute configuration (master node only)::
59
60     $ gnt-cluster redist-conf
61
62 #. Restart daemons again on all nodes::
63
64     $ /etc/init.d/ganeti restart
65
66 #. Enable the watcher again (master node only)::
67
68     $ gnt-cluster watcher continue
69
70 #. Verify cluster (master node only)::
71
72     $ gnt-cluster verify
73
74
75 2.0 releases
76 ------------
77
78 2.0.3 to 2.0.4
79 ~~~~~~~~~~~~~~
80
81 No changes needed except restarting the daemon; but rollback to 2.0.3 might
82 require configuration editing.
83
84 If you're using Xen-HVM instances, please double-check the network
85 configuration (``nic_type`` parameter) as the defaults might have changed:
86 2.0.4 adds any missing configuration items and depending on the version of the
87 software the cluster has been installed with, some new keys might have been
88 added.
89
90 2.0.1 to 2.0.2/2.0.3
91 ~~~~~~~~~~~~~~~~~~~~
92
93 Between 2.0.1 and 2.0.2 there have been some changes in the handling of block
94 devices, which can cause some issues. 2.0.3 was then released which adds two
95 new options/commands to fix this issue.
96
97 If you use DRBD-type instances and see problems in instance start or
98 activate-disks with messages from DRBD about "lower device too small" or
99 similar, it is recoomended to:
100
101 #. Run ``gnt-instance activate-disks --ignore-size $instance`` for each
102    of the affected instances
103 #. Then run ``gnt-cluster repair-disk-sizes`` which will check that
104    instances have the correct disk sizes
105
106 1.2 to 2.0
107 ----------
108
109 Prerequisites:
110
111 - Ganeti 1.2.7 is currently installed
112 - All instances have been migrated from DRBD 0.7 to DRBD 8.x (i.e. no
113   ``remote_raid1`` disk template)
114 - Upgrade to Ganeti 2.0.0~rc2 or later (~rc1 and earlier don't have the needed
115   upgrade tool)
116
117 In the below steps, replace :file:`/var/lib` with ``$libdir`` if Ganeti was not
118 installed with this prefix (e.g. :file:`/usr/local/var`). Same for
119 :file:`/usr/lib`.
120
121 Execution (all steps are required in the order given):
122
123 #. Make a backup of the current configuration, for safety::
124
125     $ cp -a /var/lib/ganeti /var/lib/ganeti-1.2.backup
126
127 #. Stop all instances::
128
129     $ gnt-instance stop --all
130
131 #. Make sure no DRBD device are in use, the following command should show no
132    active minors::
133
134     $ gnt-cluster command grep cs: /proc/drbd | grep -v cs:Unconf
135
136 #. Stop the node daemons and rapi daemon on all nodes (note: should be logged
137    in not via the cluster name, but the master node name, as the command below
138    will remove the cluster ip from the master node)::
139
140     $ gnt-cluster command /etc/init.d/ganeti stop
141
142 #. Install the new software on all nodes, either from packaging (if available)
143    or from sources; the master daemon will not start but give error messages
144    about wrong configuration file, which is normal
145 #. Upgrade the configuration file::
146
147     $ /usr/lib/ganeti/tools/cfgupgrade12 -v --dry-run
148     $ /usr/lib/ganeti/tools/cfgupgrade12 -v
149
150 #. Make sure ``ganeti-noded`` is running on all nodes (and start it if
151    not)
152 #. Start the master daemon::
153
154     $ ganeti-masterd
155
156 #. Check that a simple node-list works::
157
158     $ gnt-node list
159
160 #. Redistribute updated configuration to all nodes::
161
162     $ gnt-cluster redist-conf
163     $ gnt-cluster copyfile /var/lib/ganeti/known_hosts
164
165 #. Optional: if needed, install RAPI-specific certificates under
166    :file:`/var/lib/ganeti/rapi.pem` and run::
167
168     $ gnt-cluster copyfile /var/lib/ganeti/rapi.pem
169
170 #. Run a cluster verify, this should show no problems::
171
172     $ gnt-cluster verify
173
174 #. Remove some obsolete files::
175
176     $ gnt-cluster command rm /var/lib/ganeti/ssconf_node_pass
177     $ gnt-cluster command rm /var/lib/ganeti/ssconf_hypervisor
178
179 #. Update the xen pvm (if this was a pvm cluster) setting for 1.2
180    compatibility::
181
182     $ gnt-cluster modify -H xen-pvm:root_path=/dev/sda
183
184 #. Depending on your setup, you might also want to reset the initrd parameter::
185
186     $ gnt-cluster modify -H xen-pvm:initrd_path=/boot/initrd-2.6-xenU
187
188 #. Reset the instance autobalance setting to default::
189
190     $ for i in $(gnt-instance list -o name --no-headers); do \
191        gnt-instance modify -B auto_balance=default $i; \
192       done
193
194 #. Optional: start the RAPI demon::
195
196     $ ganeti-rapi
197
198 #. Restart instances::
199
200     $ gnt-instance start --force-multiple --all
201
202 At this point, ``gnt-cluster verify`` should show no errors and the migration
203 is complete.
204
205 1.2 releases
206 ------------
207
208 1.2.4 to any other higher 1.2 version
209 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
210
211 No changes needed. Rollback will usually require manual edit of the
212 configuration file.
213
214 1.2.3 to 1.2.4
215 ~~~~~~~~~~~~~~
216
217 No changes needed. Note that going back from 1.2.4 to 1.2.3 will require manual
218 edit of the configuration file (since we added some HVM-related new
219 attributes).
220
221 1.2.2 to 1.2.3
222 ~~~~~~~~~~~~~~
223
224 No changes needed. Note that the drbd7-to-8 upgrade tool does a disk format
225 change for the DRBD metadata, so in theory this might be **risky**. It is
226 advised to have (good) backups before doing the upgrade.
227
228 1.2.1 to 1.2.2
229 ~~~~~~~~~~~~~~
230
231 No changes needed.
232
233 1.2.0 to 1.2.1
234 ~~~~~~~~~~~~~~
235
236 No changes needed. Only some bugfixes and new additions that don't affect
237 existing clusters.
238
239 1.2.0 beta 3 to 1.2.0
240 ~~~~~~~~~~~~~~~~~~~~~
241
242 No changes needed.
243
244 1.2.0 beta 2 to beta 3
245 ~~~~~~~~~~~~~~~~~~~~~~
246
247 No changes needed. A new version of the debian-etch-instance OS (0.3) has been
248 released, but upgrading it is not required.
249
250 1.2.0 beta 1 to beta 2
251 ~~~~~~~~~~~~~~~~~~~~~~
252
253 Beta 2 switched the config file format to JSON. Steps to upgrade:
254
255 #. Stop the daemons (``/etc/init.d/ganeti stop``) on all nodes
256 #. Disable the cron job (default is :file:`/etc/cron.d/ganeti`)
257 #. Install the new version
258 #. Make a backup copy of the config file
259 #. Upgrade the config file using the following command::
260
261     $ /usr/share/ganeti/cfgupgrade --verbose /var/lib/ganeti/config.data
262
263 #. Start the daemons and run ``gnt-cluster info``, ``gnt-node list`` and
264    ``gnt-instance list`` to check if the upgrade process finished successfully
265
266 The OS definition also need to be upgraded. There is a new version of the
267 debian-etch-instance OS (0.2) that goes along with beta 2.
268
269 .. vim: set textwidth=72 :
270 .. Local Variables:
271 .. mode: rst
272 .. fill-column: 72
273 .. End: