openstack/kolla-ansible
Code Issues Proposed changes

Document upgrading for operators

Browse Source 
This documents the basics of upgrades.

Partially implements: blueprint documentation-rework
Change-Id: I042179aec0e4a43b82f5ccaf6262217301ae46c6
This commit is contained in:
Steven Dake 2016-05-16 13:54:27 -07:00
parent fca876cdd1
commit aab9e5030f
1 changed files with 56 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

57
doc/operating-kolla.rst
View File

@ -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
===========