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: