Document Fuel upgrade procedure

User Guide
- 0070-introduction.rst -- mentions upgrade and links to doc
- 8000-upgrade.rst -- details about upgrade process
- create-environment/1500-name-distro -- explanation about multiple
  Ubuntu/CentOS options on the drop-down list if one upgraded
  from earlier MOSt release

contents-user.rst -- include user-guide/8000-upgrade.rst

Closes-bug: 1334463

Change-Id: I13f23ad10364506e273a69a2411b217dd858834f

contents/contents-user.rst

@@ -4,4 +4,5 @@
 .. include:: /pages/user-guide/post-install-healthchecks.rst
 .. include:: /pages/user-guide/7000-sahara-install.rst
 .. include:: /pages/user-guide/vcenter.rst
+.. include:: /pages/user-guide/8000-upgrade.rst
 .. include:: /pages/user-guide/cli.rst

pages/user-guide/0070-introduction.rst

@@ -7,8 +7,15 @@ Introduction to the User Guide
 ==============================
 
 This guide gives instructions for using
-the Fuel Master node and the graphical Fuel screens
+the Fuel Master Node and the graphical Fuel screens
 to deploy a Mirantis OpenStack environment.
+
+If you already have a deployed Fuel Master Node based on v5.0,
+go to :ref:`upgrade-ug` for instructions about
+upgrading to v5.0.1.
+If you are deploying Mirantis OpenStack 5.x for the first time,
+continue reading this document for instructions.
+
 Before you do the procedures in this document,
 you should work through the information and procedures in the
 :ref:`Planning Guide<planning-guide>`.

pages/user-guide/2000-deploy-new-environment.rst

@@ -183,6 +183,31 @@ see :ref:`linux-distro-plan`.
 This is the operating system that will be installed
 on the Controller, Compute, and Storage nodes in the environment.
 
+If you have upgraded Fuel from an earlier release,
+the drop-down list contains options for the older Fuel releases
+as well as the current releases.
+Each option is identified by the IceHouse Release number
+and the Fuel Release number
+For example,
+if you upgraded from Mirantis OpenStack 5.0 to 5.0.1,
+you will have the following options:
+
+::
+
+    Icehouse on Ubuntu 12.04.4 (2014.1)
+    Icehouse on CentOS 6.5 (2014.1)
+    Icehouse on Ubuntu 12.04.4 (2014.1.1-5.0.1)
+    Icehouse on CentOS 6.5 (2014.1.1-5.0.1)
+
+The "2014.1.1" string in the third and fourth options
+match the Icehouse release provided for Fuel 5.0.1.
+The "2014.1" string in the first and second options
+match the Icehouse release that was provided for Fuel 5.0.
+
+If you did a fresh install of Mirantis OpentStack 5.0.1
+rather than upgrading from 5.0,
+you will only see the options for 5.0.1.
+
 .. raw:: pdf
 
   PageBreak

pages/user-guide/8000-upgrade.rst

@@ -0,0 +1,72 @@
+.. _upgrade-ug:
+
+Upgrade from an Earlier Version
+===============================
+
+If you have a functional Fuel 5.0 cloud environment,
+you can install the 5.0.1 onto the Fuel Master Node.
+After you do this, your new Fuel 5.0.1 Fuel console
+can manage your existing 5.0 OpenStack environment(s),
+create new 5.0 OpenStack environments,
+as well as create and manage new 5.0.1 OpenStack environments.
+
+The following upgrade functionality is not available for Fuel 5.0.1
+but is planned for upcoming releases:
+
+- Ability to patch the OpenStack environment
+  **within the same OpenStack release**.
+  For example, you will be able to patch
+  your OpenStack Icehouse environment
+  to a later version of Icehouse.
+
+- Ability to upgrade an OpenStack cloud environment
+  to a new OpenStack release.
+  For example, you will be able to perform inplace upgrade
+  of your OpenStack Icehouse environment
+  (Mirantis OpenStack 5.x)
+  to the OpenStack Juno environment
+  (Mirantis OpenStack 6.x).
+
+Note that you cannot do an in-place upgrade of an environment
+that is running Mirantis OpenStack 4.x or earlier.
+You must, instead, redeploy your environment
+to use the new release.
+
+To upgrade the Fuel Master Node
+that manages an existing Mirantis OpenStack 5.0 cloud environment:
+
+#. Be sure that no installations are in progress in the environment!
+
+#. Download the upgrade tarball from
+   `<http://software.mirantis.com>` to a local system.
+
+#. Use **scp** or your SSH client to copy the tarball to a location on the
+   Fuel Master Node disk that has adequate space, such as */var/tmp*.
+
+#. Extract tarball contents:
+
+    ::
+
+       cd /var/tmp  # Use the directory where the tarball is located
+       tar -xf xxx.tar
+
+#. Run the upgrade script from that same directory:
+
+    ::
+
+       ./upgrade.sh
+
+   **Do not rush to interrupt the upgrade!**
+   The upgrade process can take 30-60 minutes.
+   Some operations (such as uploading images) take some time;
+   the listing of updated files may slow down,
+   but this does not mean that the upgrade process has hung.
+
+When the upgrade is complete,
+the following messages will appear on the Fuel UI:
+
+   ::
+
+      New release available: Icehouse on Ubuntu 12.04.4 (2014.1.1-5.0.1)
+      New release available: Icehouse on CentOS 6.5 (2014.1.1-5.0.1)
+