This is an automated email from the ASF dual-hosted git repository.
paul_a pushed a commit to branch 4.13
in repository https://gitbox.apache.org/repos/asf/cloudstack-documentation.git
The following commit(s) were added to refs/heads/4.13 by this push:
new b371c63 Add warning about customisations when upgrading (#71)
b371c63 is described below
commit b371c63c069ee683b045771f535d449d7450a0ca
Author: Andrija Panic <45762285+andrijapani...@users.noreply.github.com>
AuthorDate: Fri Oct 11 17:25:55 2019 +0200
Add warning about customisations when upgrading (#71)
---
.gitignore | 3 +-
.../upgrading/upgrade/_customisation_warnings.rst | 72 ++++++++++++++++++++++
source/upgrading/upgrade/upgrade-4.10.rst | 60 ++++++++++--------
source/upgrading/upgrade/upgrade-4.11.rst | 50 ++++++++-------
source/upgrading/upgrade/upgrade-4.12.rst | 60 +++++++++---------
source/upgrading/upgrade/upgrade-4.9.rst | 68 +++++++++++---------
6 files changed, 209 insertions(+), 104 deletions(-)
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 @@ 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.
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 @@ 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,11 +141,6 @@ 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.
@@ -139,7 +148,7 @@ 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.
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 @@ 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
@@ -46,7 +54,6 @@ Upgrade Steps:
.. include:: _sysvm_templates.rst
-
Packages repository
-------------------
@@ -59,7 +66,7 @@ Create RPM or Debian packages (as appropriate) and a
repository from
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 @@ Backup current database
$ 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 @@ 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.
@@ -139,7 +147,7 @@ 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.12
We'll change it to point to the new package repository:
@@ -176,25 +184,20 @@ read as appropriate for your |version| repository.
$ 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 @@ read as appropriate for your |version| repository.
$ 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 @@ Hypervisor: VMware
No additional steps are requried for the VMware Hypervisor for this upgrade.
-.. _kvm411:
+.. _kvm412:
Hypervisor: KVM
-^^^^^^^^^^^^^^^
+#################
KVM on Ubuntu
""""""""""""""
@@ -314,6 +317,7 @@ hosts.
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 @@ 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 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 @@ Backup current database
.. _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 @@ 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-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 @@ This file should have one line, which contains:
.. 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 @@ read as appropriate for your |version| repository.
.. _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 @@ packages. If not, skip to hypervisors section
:ref:`upg_hyp_49`.
.. 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 @@ This file should have content similar to the following:
[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 @@ read as appropriate for your |version| repository.
.. _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 @@ to
``/usr/share/cloudstack-common/scripts/vm/hypervisor/xenserver``.
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 @@ the plain text password
.. _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 @@ hosts.
KVM on CentOS/RHEL
-^^^^^^^^^^^^^^^^^^
+"""""""""""""""""""
+
For KVM hosts, upgrade the ``cloudstack-agent`` package
#. Configure the :ref:`rpm-repo49` as detailed above.
