Add warning about customisations when upgrading (apache#71)

Author: andrijapanicsb

.gitignore

@@ -1,2 +1,3 @@
 build/
-.vscode
+.vscode
+source/_build/

source/upgrading/upgrade/_customisation_warnings.rst

@@ -0,0 +1,72 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+   or more contributor license agreements.  See the NOTICE file
+   distributed with this work for additional information#
+   regarding copyright ownership.  The ASF licenses this file
+   to you under the Apache License, Version 2.0 (the
+   "License"); you may not use this file except in compliance
+   with the License.  You may obtain a copy of the License at
+   http://www.apache.org/licenses/LICENSE-2.0
+   Unless required by applicable law or agreed to in writing,
+   software distributed under the License is distributed on an
+   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+   KIND, either express or implied.  See the License for the
+   specific language governing permissions and limitations
+   under the License.
+
+.. sub-section included in upgrade notes.
+
+CloudStack Customisations
+--------------------------
+
+There are a number of ways in which administrators can customise CloudStack.  During an
+upgrade, a number of these could be overridden.  Therefore steps should be taken to ensure
+that they can be restored after the upgrade is completed.
+
+
+Guest OS mappings
+##################
+
+A new CloudStack release often brings compatibility with new hypervisors, and therefore 
+new Guest OS mappings. An API is provided to manually add guest OSes and the
+relevant hypervisor mappings, however, there is a high probability that manually 
+added guest OSes and/or mappings would conflict with guest OSes and/or mappings
+added as part of a version upgrade.
+
+It is therefore essential to remove any Guest OS mappings that were manually added 
+in order to ensure a successful upgrade.  If need be, any custom Guest OS mappings 
+still 'missing' after an upgrade can be re-added after the upgrade.
+That means that any custom added rows in the *guest_os*, *guest_os_hypervisor*, 
+*guest_os_details* and *guest_os_category* database tables, should be removed 
+prior to the upgrade, and added later if needed.
+
+.. warning::
+      Manually added guest OS mappings can cause the upgrade process to fail.
+
+
+Customised CSS
+###############
+
+If you have altered the CSS files in order to customise the appearance of the CloudStack UI,
+you should make a backup copy as the installed CSS files are likely to be overwritten during
+any upgrade.
+
+You should inspect a 'diff' of your customised css files and the new versions, and then
+reapply your changes to the new files as the new versions may contain changes to better display existing
+elements or have new entries to support new UI elements.
+
+Plugins
+#######
+
+If you have 3rd party plugins installed, you should backup your plugins directories and the
+plugins.js file.  While the plugins directories *should* remain untouched, the plugins.js
+file is likely to be overwritten.
+
+3rd Party Integrations
+#######################
+
+CloudStack is put through extensive regression testing during a release cycle, however 
+the numerous 3rd party integrations which are available cannot all be tested by the 
+community nor indeed may the community know about many of them. Therefore it is essential
+that you verify that your integrations will continue to work after an upgrade through thorough
+testing and checking with the vendor/supplier of your integrations.
+

source/upgrading/upgrade/upgrade-4.10.rst

@@ -32,17 +32,31 @@ working on a production system.
     The following upgrade instructions should be performed regardless of
     hypervisor type.
 
-Upgrade Steps:
+Overview of Upgrade Steps:
+----------------------------
 
+#. Check any customisations and integrations
+#. Upload the |sysvm64-version| System VM template if not already using it.
+#. Stop all running management servers
 #. Backup CloudStack database (MySQL)
-#. Add package repository for MySQL connector
-#. Upgrade CloudStack management server(s)
+#. Upgrade 1st CloudStack management server
 #. Update hypervisors specific dependencies
+#. Restart 1st management server
+#. Check that your upgraded environment works as expected
+#. Upgrade and restart the remaining management servers
+
 
 Apache CloudStack 4.10.0.0 users who are upgrading to 4.11.0.0 should read the
 following discussion and workaround for a db-upgrade issue:
 http://markmail.org/message/f42kqr3mx4r4hgih
 
+.. include:: _customisation_warnings.rst
+
+.. warning::
+    If you are not already using the |sysvm64-version| System VM template you will need to 
+    upgrade your System VM template prior to performing the upgrade of the 
+    CloudStack packages.
+
 .. include:: _sysvm_templates.rst
 
 Packages repository
@@ -109,9 +123,14 @@ Backup current database
 
 
 .. _ubuntu410:
+.. _apt-repo410:
+
+Management Server
+-----------------
+
+Ubuntu
+######
 
-Management Server on Ubuntu
----------------------------
 
 If you are using Ubuntu, follow this procedure to upgrade your packages. If
 not, skip to step :ref:`rhel410`.
@@ -126,14 +145,8 @@ each system with CloudStack packages. This means all management
 servers, and any hosts that have the KVM agent. (No changes should
 be necessary for hosts that are running VMware or Xen.)
 
-
-.. _apt-repo410:
-
 .. include:: _java_8_ubuntu.rst
 
-CloudStack apt repository
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
 Start by opening ``/etc/apt/sources.list.d/cloudstack.list`` on
 any systems that have CloudStack packages installed.
 
@@ -179,9 +192,10 @@ read as appropriate for your |version| repository.
 
 
 .. _rhel410:
+.. _rpm-repo410:
 
-Management Server on CentOS/RHEL
---------------------------------
+CentOS/RHEL
+##############
 
 If you are using CentOS or RHEL, follow this procedure to upgrade your
 packages. If not, skip to hypervisors section :ref:`upg_hyp_410`.
@@ -191,12 +205,6 @@ packages. If not, skip to hypervisors section :ref:`upg_hyp_410`.
    supplied packages for CloudStack. If you've created your own packages and
    yum repository, substitute your own URL for the ones used in these examples.
 
-
-.. _rpm-repo410:
-
-CloudStack RPM repository
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
 The first order of business will be to change the yum repository
 for each system with CloudStack packages. This means all
 management servers, and any hosts that have the KVM agent.
@@ -250,8 +258,11 @@ read as appropriate for your |version| repository.
 
 .. _upg_hyp_410:
 
+Upgrade Hypervisors
+-------------------
+
 Hypervisor: XenServer
----------------------
+#####################
 
 **(XenServer only)** Copy vhd-utils file on CloudStack management servers.
 Copy the file `vhd-utils <http://download.cloudstack.org/tools/vhd-util>`_
@@ -264,7 +275,7 @@ to ``/usr/share/cloudstack-common/scripts/vm/hypervisor/xenserver``.
 
 
 Hypervisor: VMware
-------------------
+#####################
 
 .. warning::
    For VMware hypervisor CloudStack management server packages must be
@@ -338,10 +349,10 @@ the plain text password
 .. _kvm410:
 
 Hypervisor: KVM
----------------
+#################
 
 KVM on Ubuntu
-^^^^^^^^^^^^^
+""""""""""""""
 
 (KVM only) Additional steps are required for each KVM host. These
 steps will not affect running guests in the cloud. These steps are
@@ -379,7 +390,8 @@ hosts.
 
 
 KVM on CentOS/RHEL
-^^^^^^^^^^^^^^^^^^
+"""""""""""""""""""
+
 For KVM hosts, upgrade the ``cloudstack-agent`` package
 
 #. Configure the :ref:`rpm-repo410` as detailed above.

source/upgrading/upgrade/upgrade-4.11.rst

@@ -32,13 +32,22 @@ working on a production system.
     The following upgrade instructions should be performed regardless of
     hypervisor type.
 
-Upgrade Steps:
+Overview of Upgrade Steps:
+----------------------------
 
+#. Check any customisations and integrations
 #. Upload the |sysvm64-version| System VM template if not already using it.
+#. Stop all running management servers
 #. Backup CloudStack database (MySQL)
-#. Add package repository for MySQL connector
-#. Upgrade CloudStack management server(s)
+#. Upgrade 1st CloudStack management server
 #. Update hypervisors specific dependencies
+#. Restart 1st management server
+#. Check that your upgraded environment works as expected
+#. Upgrade and restart the remaining management servers
+
+
+
+.. include:: _customisation_warnings.rst
 
 .. warning::
     If you are not already using the |sysvm64-version| System VM template you will need to 
@@ -110,9 +119,14 @@ Backup current database
 
 
 .. _ubuntu411:
+.. _apt-repo411:
+
+Management Server
+-----------------
+
+Ubuntu
+######
 
-Management Server on Ubuntu
----------------------------
 
 If you are using Ubuntu, follow this procedure to upgrade your packages. If
 not, skip to step :ref:`rhel411`.
@@ -127,19 +141,14 @@ each system with CloudStack packages. This means all management
 servers, and any hosts that have the KVM agent. (No changes should
 be necessary for hosts that are running VMware or Xen.)
 
-.. _apt-repo411:
-
-CloudStack apt repository
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
 Start by opening ``/etc/apt/sources.list.d/cloudstack.list`` on
 any systems that have CloudStack packages installed.
 
 This file should have one line, which contains:
 
 .. parsed-literal::
 
-   deb http://download.cloudstack.org/ubuntu precise 4.10
+   deb http://download.cloudstack.org/ubuntu precise 4.11
 
 We'll change it to point to the new package repository:
 
@@ -177,9 +186,10 @@ read as appropriate for your |version| repository.
 
 
 .. _rhel411:
+.. _rpm-repo411:
 
-Management Server on CentOS/RHEL
---------------------------------
+CentOS/RHEL
+##############
 
 If you are using CentOS or RHEL, follow this procedure to upgrade your
 packages. If not, skip to hypervisors section :ref:`upg_hyp_411`.
@@ -189,12 +199,6 @@ packages. If not, skip to hypervisors section :ref:`upg_hyp_411`.
    supplied packages for CloudStack. If you've created your own packages and
    yum repository, substitute your own URL for the ones used in these examples.
 
-
-.. _rpm-repo411:
-
-CloudStack RPM repository
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
 The first order of business will be to change the yum repository
 for each system with CloudStack packages. This means all
 management servers, and any hosts that have the KVM agent.
@@ -250,15 +254,14 @@ read as appropriate for your |version| repository.
 Upgrade Hypervisors
 -------------------
 
-
 Hypervisor: XenServer
-^^^^^^^^^^^^^^^^^^^^^
+#####################
 
 No additional steps are required wrt for XenServer Hypervisor for this upgrade.
 
 
 Hypervisor: VMware
-------------------
+###################
 
 .. warning::
    For VMware hypervisor CloudStack management server packages must be
@@ -271,7 +274,7 @@ No additional steps are requried for the VMware Hypervisor for this upgrade.
 .. _kvm411:
 
 Hypervisor: KVM
-^^^^^^^^^^^^^^^
+#################
 
 KVM on Ubuntu
 """"""""""""""
@@ -313,6 +316,7 @@ hosts.
 
 KVM on CentOS/RHEL
 """""""""""""""""""
+
 For KVM hosts, upgrade the ``cloudstack-agent`` package
 
 #. Configure the :ref:`rpm-repo411` as detailed above.