Upgrade Instruction from 4.5.x

This section will guide you from CloudStack 4.5.x to CloudStack 4.15.0.0.

Any steps that are hypervisor-specific will be called out with a note.

We recommend reading through this section once or twice before beginning your upgrade procedure, and working through it on a test system before working on a production system.

Note

The following upgrade instructions should be performed regardless of hypervisor type.

Upgrade Steps:

  1. Check any customisations and integrations
  2. Upload the 4.15.0 System VM template if not already using it.
  3. Stop all running management servers
  4. Backup CloudStack database (MySQL)
  5. Add package repository for MySQL connector
  6. Upgrade CloudStack management server(s)
  7. Update hypervisors specific dependencies

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.

Warning

If you are not already using the 4.15.0 System VM template you will need to upgrade your System VM template prior to performing the upgrade of the CloudStack packages.

Update System-VM templates

  1. While running the existing 4.5.x system, log in to the UI as the root administrator.

  2. In the left navigation bar, click Templates.

  3. In Select view, click Templates.

  4. Click Register template. The Register template dialog box is displayed.

  5. In the Register template dialog box, specify the following values (do not change these):

    HypervisorDescription
    XenServer

    Name: systemvm-xenserver-4.15.0

    Description: systemvm-xenserver-4.15.0

    URL: http://download.cloudstack.org/systemvm/4.15/systemvmtemplate-4.15.0-xen.vhd.bz2

    Zone: Choose the zone where this hypervisor is used

    Hypervisor: XenServer

    Format: VHD

    OS Type: Other Linux (64-bit)

    Extractable: no

    Password Enabled: no

    Public: no

    Featured: no

    Routing: no

    KVM

    Name: systemvm-kvm-4.15.0

    Description: systemvm-kvm-4.15.0

    URL: http://download.cloudstack.org/systemvm/4.15/systemvmtemplate-4.15.0-kvm.qcow2.bz2

    Zone: Choose the zone where this hypervisor is used

    Hypervisor: KVM

    Format: QCOW2

    OS Type: Debian GNU/Linux 7.0 (64-bit) (or the highest Debian release number available in the dropdown)

    Extractable: no

    Password Enabled: no

    Public: no

    Featured: no

    Routing: no

    VMware

    Name: systemvm-vmware-4.15.0

    Description: systemvm-vmware-4.15.0

    URL: http://download.cloudstack.org/systemvm/4.15/systemvmtemplate-4.15.0-vmware.ova

    Zone: Choose the zone where this hypervisor is used

    Hypervisor: VMware

    Format: OVA

    OS Type: Other Linux (64-bit)

    Extractable: no

    Password Enabled: no

    Public: no

    Featured: no

    Routing: no

    HyperV

    Name: systemvm-hyperv-4.15.0

    Description: systemvm-hyperv-4.15.0

    URL: http://download.cloudstack.org/systemvm/4.15/systemvmtemplate-4.15.0-hyperv.vhd.zip

    Zone: Choose the zone where this hypervisor is used

    Hypervisor: Hyper-V

    Format: VHD

    OS Type: Debian GNU/Linux 7.0 (64-bit) (or the highest Debian release number available in the dropdown)

    Extractable: no

    Password Enabled: no

    Public: no

    Featured: no

    Routing: no

  6. Watch the screen to be sure that the template downloads successfully and enters the READY state. Do not proceed until this is successful.

Java Version Requirement

CloudStack 4.15 requires installation of Java 11 JRE for management server and the KVM agent. On installing or upgrading cloudstack-management and/or cloudstack-agent packages, please configure Java 11 as the default java version using:

  1. $ sudo alternatives --config java

Note: For Ubuntu distributions where the openjdk-11 packages are not available from the main repositories, the JRE can be installed from an external PPA such as openjdk-r. The PPA can be added before installation/upgrade:

  1. $ sudo add-apt-repository ppa:openjdk-r/ppa
  2. $ sudo apt-get update

Packages repository

Most users of CloudStack manage the installation and upgrades of CloudStack with one of Linux’s predominant package systems, RPM or APT. This guide assumes you’ll be using RPM and Yum (for Red Hat Enterprise Linux or CentOS), or APT and Debian packages (for Ubuntu).

Create RPM or Debian packages (as appropriate) and a repository from the 4.15.0.0 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 Management Server on Ubuntu or Management Server on CentOS/RHEL and Hypervisor: KVM hosts upgrade.

Instructions for creating packages from the CloudStack source are in the CloudStack Installation Guide.

Database Preparation

Backup current database

  1. Stop your management server or servers. Run this on all management server hosts:

    1. $ sudo service cloudstack-management stop

  2. If you are running a usage server or usage servers, stop those as well:

    1. $ sudo service cloudstack-usage stop

  3. Make a backup of your MySQL database. If you run into any issues or need to roll back the upgrade, this will assist in debugging or restoring your existing environment. You’ll be prompted for your password.

    1. $ mysqldump -u root -p cloud > cloud-backup_`date '+%Y-%m-%d'.sql
    2. $ mysqldump -u root -p cloud_usage > cloud_usage-backup_`date '+%Y-%m-%d'.sql

Management Server on Ubuntu

If you are using Ubuntu, follow this procedure to upgrade your packages. If not, skip to step Management Server on CentOS/RHEL.

Time zone requirements

As of CloudStack 4.14, you must explicitly configure time zone either in the MySQL server or JDBC driver (db.properties). In previous CloudStack versions, UTC time zone was assumed by default (all event’s have UTC time stamps), so the same UTC time zone should now be explicitly configured.

You can do this by editing the /etc/cloudstack/management/db.properties file and adding “serverTimezone=UTC” to the “db.cloud.url.params=” and “db.usage.url.params=” lines. Example lines, from a clean 4.14 installation, are given below:

  1. db.cloud.url.params=prepStmtCacheSize=517&cachePrepStmts=true&sessionVariables=sql_mode='STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION'&serverTimezone=UTC
  2. db.usage.url.params=serverTimezone=UTC

Note

Community Packages: This section assumes you’re using the community supplied packages for CloudStack. If you’ve created your own packages and APT repository, substitute your own URL for the ones used in these examples.

The first order of business will be to change the sources list for 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.)

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:

  1. deb http://download.cloudstack.org/ubuntu precise 4.5

Ubuntu 12.04 Precise is not supported with CloudStack 4.15.0.0, so make sure to have updated your management servers to Xenial or Bionic first.

We’ll change it to point to the new package repository:

  1. deb http://download.cloudstack.org/ubuntu bionic 4.13

Setup the public key for the above repository:

  1. wget -qO - http://download.cloudstack.org/release.asc | sudo apt-key add -

If you’re using your own package repository, change this line to read as appropriate for your 4.15 repository.

  1. Now update your apt package list:

    1. $ sudo apt-get update

  2. Now that you have the repository configured, it’s time to upgrade the cloudstack-management package.

    1. $ sudo apt-get upgrade cloudstack-management

  3. If you use CloudStack usage server

    1. $ sudo apt-get upgrade cloudstack-usage

Management Server on CentOS/RHEL

If you are using CentOS or RHEL, follow this procedure to upgrade your packages. If not, skip to hypervisors section Hypervisor: XenServer.

Time zone requirements

As of CloudStack 4.14, you must explicitly configure time zone either in the MySQL server or JDBC driver (db.properties). In previous CloudStack versions, UTC time zone was assumed by default (all event’s have UTC time stamps), so the same UTC time zone should now be explicitly configured.

You can do this by editing the /etc/cloudstack/management/db.properties file and adding “serverTimezone=UTC” to the “db.cloud.url.params=” and “db.usage.url.params=” lines. Example lines, from a clean 4.14 installation, are given below:

  1. db.cloud.url.params=prepStmtCacheSize=517&cachePrepStmts=true&sessionVariables=sql_mode='STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION'&serverTimezone=UTC
  2. db.usage.url.params=serverTimezone=UTC

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.

Install new MySQL connector

Starting with 4.9.0, cloudstack-management RPM’s now depend on the mysql-connector-python package. Therefore Apache CloudStack 4.15.0.0 requires the instalation of the MySQL connector on CentOS.

MySQL connector RPM repository

Add a new yum repo /etc/yum.repos.d/mysql.repo:

  1. [mysql-community]
  2. name=MySQL Community connectors
  3. baseurl=http://repo.mysql.com/yum/mysql-connectors-community/el/$releasever/$basearch/
  4. enabled=1
  5. gpgcheck=1

Import GPG public key from MySQL:

  1. rpm --import http://repo.mysql.com/RPM-GPG-KEY-mysql

Install mysql-connector

  1. yum install mysql-connector-python

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.

(No changes should be necessary for hosts that are running VMware or Xen.)

Start by opening /etc/yum.repos.d/cloudstack.repo on any systems that have CloudStack packages installed.

This file should have content similar to the following:

  1. [apache-cloudstack]
  2. name=Apache CloudStack
  3. baseurl=http://download.cloudstack.org/rhel/4.5/
  4. enabled=1
  5. gpgcheck=0

If you are using the community provided package repository, change the base url to http://download.cloudstack.org/centos/$releasever/4.13/.

Setup the GPG public key if you wish to enable gpgcheck=1:

  1. rpm --import http://download.cloudstack.org/RPM-GPG-KEY

If you’re using your own package repository, change this line to read as appropriate for your 4.15 repository.

  1. Remove the deprecated dependency for awsapi.

    1. $ sudo rpm -e --nodeps cloudstack-awsapi

  2. Now that you have the repository configured, it’s time to upgrade the cloudstack-management.

    1. $ sudo yum upgrade cloudstack-management

  3. If you use CloudStack usage server

    1. $ sudo yum upgrade cloudstack-usage

Hypervisor: XenServer

(XenServer only) Copy vhd-utils file on CloudStack management servers. Copy the file vhd-utils to /usr/share/cloudstack-common/scripts/vm/hypervisor/xenserver.

  1. 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 build using “noredist”. Refer to Building Non-OSS

(VMware only) Additional steps are required for each VMware cluster. These steps will not affect running guests in the cloud. These steps are required only for clouds using VMware clusters:

  1. Stop the Management Server:

    1. $ sudo service cloudstack-management stop

  2. Generate the encrypted equivalent of your vCenter password:

    1. $ java -classpath /usr/share/cloudstack-common/lib/jasypt-1.9.2.jar org.jasypt.intf.cli.JasyptPBEStringEncryptionCLI encrypt.sh input="_your_vCenter_password_" password="cat /etc/cloudstack/management/key" verbose=false

Store the output from this step, we need to add this in cluster_details table and vmware_data_center tables in place of the plain text password

  1. Find the ID of the row of cluster_details table that you have to update:

    1. $ mysql -u <username> -p<password>
    1. select * from cloud.cluster_details;

  2. Update the plain text password with the encrypted one

    1. update cloud.cluster_details set value = '_ciphertext_from_step_1_'
    2. where id = _id_from_step_2_;

  3. Confirm that the table is updated:

    1. select * from cloud.cluster_details;

  4. Find the ID of the correct row of vmware_data_center that you

    want to update

    1. select * from cloud.vmware_data_center;

  5. update the plain text password with the encrypted one:

    1. update cloud.vmware_data_center set password = '_ciphertext_from_step_1_'
    2. where id = _id_from_step_5_;

  6. Confirm that the table is updated:

    1. select * from cloud.vmware_data_center;

Hypervisor: KVM

(KVM only) Additional steps are required for each KVM host. These steps will not affect running guests in the cloud. These steps are required only for clouds using KVM as hosts and only on the KVM hosts.

  1. Configure the APT repo as detailed above.

  2. Stop the running agent.

    1. $ sudo service cloudstack-agent stop

  3. Update the agent software.

    1. $ sudo apt-get upgrade cloudstack-agent

  4. Verify that the file /etc/cloudstack/agent/environment.properties has a

    line that reads:

    1. paths.script=/usr/share/cloudstack-common

    If not, add the line.

  5. Start the agent.

    1. $ sudo service cloudstack-agent start

For KVM hosts, upgrade the cloudstack-agent package

  1. Configure the CloudStack RPM repository as detailed above.

    1. $ sudo yum upgrade cloudstack-agent

  2. Verify that the file /etc/cloudstack/agent/environment.properties has a line that reads:

    1. paths.script=/usr/share/cloudstack-common

    If not, add the line.

  3. Restart the agent:

    1. $ sudo service cloudstack-agent stop
    2. $ sudo service cloudstack-agent start

Restart management services

  1. Now it’s time to start the management server

    1. $ sudo service cloudstack-management start

  2. If you use it, start the usage server

    1. $ sudo service cloudstack-usage start

System-VMs and Virtual-Routers

Once you’ve upgraded the packages on your management servers, you’ll need to restart the system VMs in order for those VMs to be rebuilt from the new systemVM template version.

Note

Restarting system VMs can be done in different ways. You can use script “cloudstack-sysvmadm” which is provided with CloudStack, or do a manual restart of system VMs or do it by using third-party tools such as Ansible. Below we are giving instructions for using the “cloudstack-sysvmadm” script.

Ensure that the admin port is set to 8096 by using the “integration.api.port” global parameter. This port is used by the cloudstack-sysvmadm script at the end of the upgrade procedure. For information about how to set this parameter, see configuration parameters Changing this parameter will require a management server restart.

If you run the cloudstack-sysvmadm script from outside the management server, make sure port 8096 is open in your local host firewall.

Warning

Never allow access to port 8096 from the public internet! The management server accepts API calls without authentication on this port, which can pose a serious security risk.

There is a script that will do this for you, all you need to do is run the script and supply the IP address for your MySQL instance and your MySQL credentials:

  1. # nohup cloudstack-sysvmadm -d IPaddress -u cloud -p password -a > sysvm.log 2>&1 &

You can monitor the log for progress. The process of restarting the system VMs can take an hour or more.

  1. # tail -f sysvm.log

The output to sysvm.log will look something like this:

  1. Stopping and starting 1 secondary storage vm(s)...
  2. Done stopping and starting secondary storage vm(s)
  3. Stopping and starting 1 console proxy vm(s)...
  4. Done stopping and starting console proxy vm(s).
  5. Stopping and starting 4 running routing vm(s)...
  6. Done restarting router(s).

After the upgrade process is complete, you can disable unauthenticated API access again by setting “integration.api.port” to 0. Don’t forget to restart the management server afterwards.