From aab9e5030fbfd36d1aafbf0eca9d703e3848bc80 Mon Sep 17 00:00:00 2001 From: Steven Dake Date: Mon, 16 May 2016 13:54:27 -0700 Subject: [PATCH] Document upgrading for operators This documents the basics of upgrades. Partially implements: blueprint documentation-rework Change-Id: I042179aec0e4a43b82f5ccaf6262217301ae46c6 --- doc/operating-kolla.rst | 57 ++++++++++++++++++++++++++++++++++++++++- 1 file changed, 56 insertions(+), 1 deletion(-) diff --git a/doc/operating-kolla.rst b/doc/operating-kolla.rst index 85affda004..f13d43f46d 100644 --- a/doc/operating-kolla.rst +++ b/doc/operating-kolla.rst @@ -6,7 +6,62 @@ Operating Kolla Upgrading ========= -TODO(all) fill this section out +Kolla's strategy for upgrades is to never make a mess and follow consistent +patterns during deployment such that upgrades from one environment to +the next are simple to automate. + +Kolla implements a one command operation for upgrading an existing deployment +consisting of a set of containers and configuration data to a new deployment. + +Kolla uses the ``x.y.z`` semver nomenclature for naming versions. Kolla's +Liberty version is ``1.0.0`` and the Mitaka version is ``2.0.0``. The Kolla +community commits to release z-stream updates every 45 days that resolve +defects in the stable version in use and publish those images to the +Docker Hub registry. To prevent confusion, the Kolla community recommends +using an alpha identifier ``x.y.z.a`` where ``a`` represents any customization +done on the part of the operator. For example, if an operator intends +to modify one of the Docker files or the repos from where the originals and +build custom images and using Liberty, the operator should start with +version 1.0.0.0 and increase alpha for each release. Alpha tag usage is +at discretion of the operator. The alpha identifier could be a number as +recommended or a string of the operator's choosing. + +If the alpha identifier is not used, Kolla will deploy or upgrade using the +version number information contained in the release. To customize the +version number uncomment openstack_version in globals.yml and specify +the version number desired. + +For example, to deploy a custom built Liberty version built with the +``kolla-build --tag 1.0.0.0`` operation, change globals.yml:: + + openstack_version: 1.0.0.0 + +Then run the command to deploy:: + + kolla-ansible deploy + +If using Liberty and a custom alpha number of 0, and upgrading to 1, change +globals.yml:: + + openstack_version: 1.0.0.1 + +Then run the command to upgrade:: + + kolla-ansible upgrade + +.. NOTE:: Varying degrees of success have been reported with upgrading + the libvirt container with a running virtual machine in it. The libvirt + upgrade still needs a bit more validation, but the Kolla commnity feels + confident this mechanism can be used with the correct Docker graph driver. + +.. NOTE:: The Kolla community recommends the btrfs or aufs graph drivers for + storing data as sometimes the LVM graph driver loses track of its reference + counting and results in an unremovable container. + +.. NOTE:: Because of system technical limitations, upgrade of a libvirt + container when using software emulation (``virt_driver=qemu`` in nova.conf), + does not work at all. This is acceptable because KVM is the recommended + virtualization driver to use with Nova. Diagnostics ===========