Add warning about customisations when upgrading (#71)
diff --git a/.gitignore b/.gitignore
index 10561bd..92e8509 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,2 +1,3 @@
build/
-.vscode
\ No newline at end of file
+.vscode
+source/_build/
diff --git a/source/upgrading/upgrade/_customisation_warnings.rst b/source/upgrading/upgrade/_customisation_warnings.rst
new file mode 100644
index 0000000..3985a32
--- /dev/null
+++ b/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.
+
diff --git a/source/upgrading/upgrade/upgrade-4.10.rst b/source/upgrading/upgrade/upgrade-4.10.rst
index 9341b1d..87b0760 100644
--- a/source/upgrading/upgrade/upgrade-4.10.rst
+++ b/source/upgrading/upgrade/upgrade-4.10.rst
@@ -32,17 +32,31 @@
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 @@
.. _ubuntu410:
+.. _apt-repo410:
-Management Server on Ubuntu
----------------------------
+Management Server
+-----------------
+
+Ubuntu
+######
+
If you are using Ubuntu, follow this procedure to upgrade your packages. If
not, skip to step :ref:`rhel410`.
@@ -126,14 +145,8 @@
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 @@
.. _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 @@
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 @@
.. _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 @@
Hypervisor: VMware
-------------------
+#####################
.. warning::
For VMware hypervisor CloudStack management server packages must be
@@ -338,10 +349,10 @@
.. _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 @@
KVM on CentOS/RHEL
-^^^^^^^^^^^^^^^^^^
+"""""""""""""""""""
+
For KVM hosts, upgrade the ``cloudstack-agent`` package
#. Configure the :ref:`rpm-repo410` as detailed above.
diff --git a/source/upgrading/upgrade/upgrade-4.11.rst b/source/upgrading/upgrade/upgrade-4.11.rst
index b2fd91a..9e88346 100644
--- a/source/upgrading/upgrade/upgrade-4.11.rst
+++ b/source/upgrading/upgrade/upgrade-4.11.rst
@@ -32,13 +32,22 @@
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 @@
.. _ubuntu411:
+.. _apt-repo411:
-Management Server on Ubuntu
----------------------------
+Management Server
+-----------------
+
+Ubuntu
+######
+
If you are using Ubuntu, follow this procedure to upgrade your packages. If
not, skip to step :ref:`rhel411`.
@@ -127,11 +141,6 @@
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.
@@ -139,7 +148,7 @@
.. 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 @@
.. _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 @@
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 @@
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 @@
.. _kvm411:
Hypervisor: KVM
-^^^^^^^^^^^^^^^
+#################
KVM on Ubuntu
""""""""""""""
@@ -313,6 +316,7 @@
KVM on CentOS/RHEL
"""""""""""""""""""
+
For KVM hosts, upgrade the ``cloudstack-agent`` package
#. Configure the :ref:`rpm-repo411` as detailed above.
diff --git a/source/upgrading/upgrade/upgrade-4.12.rst b/source/upgrading/upgrade/upgrade-4.12.rst
index abccd7e..70db11a 100644
--- a/source/upgrading/upgrade/upgrade-4.12.rst
+++ b/source/upgrading/upgrade/upgrade-4.12.rst
@@ -31,13 +31,21 @@
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
@@ -46,7 +54,6 @@
.. include:: _sysvm_templates.rst
-
Packages repository
-------------------
@@ -59,7 +66,7 @@
the |release| source, or check the Apache CloudStack downloads page at
http://cloudstack.apache.org/downloads.html
for package repositories supplied by community members. You will need
-them for :ref:`ubuntu411` or :ref:`rhel411` and :ref:`kvm411` hosts upgrade.
+them for :ref:`ubuntu412` or :ref:`rhel412` and :ref:`kvm412` hosts upgrade.
Instructions for creating packages from the CloudStack source are in the
`CloudStack Installation Guide`_.
@@ -109,10 +116,14 @@
$ mysql -u cloud -p -e 'update cloud.storage_pool set path="/var/lib/libvirt/images" where path="/var/lib/libvirt/images/"';
-.. _ubuntu411:
+.. _ubuntu412:
+.. _apt-repo412:
-Management Server on Ubuntu
----------------------------
+Management Server
+-----------------
+
+Ubuntu
+######
If you are using Ubuntu, follow this procedure to upgrade your packages. If
not, skip to step :ref:`rhel411`.
@@ -127,10 +138,7 @@
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.
@@ -139,7 +147,7 @@
.. parsed-literal::
- deb http://download.cloudstack.org/ubuntu precise 4.10
+ deb http://download.cloudstack.org/ubuntu precise 4.12
We'll change it to point to the new package repository:
@@ -176,25 +184,20 @@
$ sudo apt-get upgrade cloudstack-usage
-.. _rhel411:
+.. _rhel412:
+.. _rpm-repo412:
-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`.
+packages. If not, skip to hypervisors section :ref:`upg_hyp_412`.
.. note::
**Community Packages:** This section assumes you're using the community
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.
@@ -246,20 +249,20 @@
$ sudo yum upgrade cloudstack-usage
-.. _upg_hyp_411:
+.. _upg_hyp_412:
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
@@ -269,10 +272,10 @@
No additional steps are requried for the VMware Hypervisor for this upgrade.
-.. _kvm411:
+.. _kvm412:
Hypervisor: KVM
-^^^^^^^^^^^^^^^
+#################
KVM on Ubuntu
""""""""""""""
@@ -314,6 +317,7 @@
KVM on CentOS/RHEL
"""""""""""""""""""
+
For KVM hosts, upgrade the ``cloudstack-agent`` package
#. Configure the :ref:`rpm-repo411` as detailed above.
diff --git a/source/upgrading/upgrade/upgrade-4.9.rst b/source/upgrading/upgrade/upgrade-4.9.rst
index 3e67d53..d19e22d 100644
--- a/source/upgrading/upgrade/upgrade-4.9.rst
+++ b/source/upgrading/upgrade/upgrade-4.9.rst
@@ -32,12 +32,27 @@
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 sserver
+#. 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
+ upgrade your System VM template prior to performing the upgrade of the
+ CloudStack packages.
.. include:: _sysvm_templates.rst
@@ -105,9 +120,13 @@
.. _ubuntu49:
+.. _apt-repo49:
-Management Server on Ubuntu
----------------------------
+Management Server
+-----------------
+
+Ubuntu
+######
If you are using Ubuntu, follow this procedure to upgrade your packages. If
not, skip to step :ref:`rhel49`.
@@ -122,14 +141,8 @@
servers, and any hosts that have the KVM agent. (No changes should
be necessary for hosts that are running VMware or Xen.)
-
-.. _apt-repo49:
-
.. 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.
@@ -137,13 +150,13 @@
.. parsed-literal::
- deb http://download.cloudstack.org/ubuntu precise 4.8
+ deb http://download.cloudstack.org/ubuntu precise 4.9
We'll change it to point to the new package repository:
.. parsed-literal::
- deb http://download.cloudstack.org/ubuntu precise 4.9
+ deb http://download.cloudstack.org/ubuntu precise |version|
Setup the public key for the above repository:
@@ -175,9 +188,10 @@
.. _rhel49:
+.. _rpm-repo49:
-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_49`.
@@ -190,12 +204,6 @@
.. include:: _mysql_connector.rst
-
-.. _rpm-repo49:
-
-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.
@@ -212,7 +220,7 @@
[apache-cloudstack]
name=Apache CloudStack
- baseurl=http://download.cloudstack.org/centos/6/4.8/
+ baseurl=http://download.cloudstack.org/centos/6/4.9/
enabled=1
gpgcheck=0
@@ -248,8 +256,11 @@
.. _upg_hyp_49:
+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>`_
@@ -260,9 +271,8 @@
wget -P /usr/share/cloudstack-common/scripts/vm/hypervisor/xenserver \
http://download.cloudstack.org/tools/vhd-util
-
Hypervisor: VMware
-------------------
+###################
.. warning::
For VMware hypervisor CloudStack management server packages must be
@@ -335,11 +345,12 @@
.. _kvm49:
+
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
@@ -377,7 +388,8 @@
KVM on CentOS/RHEL
-^^^^^^^^^^^^^^^^^^
+"""""""""""""""""""
+
For KVM hosts, upgrade the ``cloudstack-agent`` package
#. Configure the :ref:`rpm-repo49` as detailed above.
