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: