Upgrade Abiquo

1. Introduction

This section describes how to upgrade from Abiquo 6.1.x to an Abiquo 6.2.x version.

To upgrade from earlier versions, first see:

For your convenience, we have also prepared the following concise upgrade document that groups the commands by servers.
However, we encourage you to use the current Upgrade Abiquo document as your main reference:

Upgrade Abiquo 6.1.x to 6.2.x distributed by servers v620

Please contact Abiquo Support for further information.

Major version upgrade table

From version

To version

Upgrade type

Notes

6.1.x

6.2.x

Standard

Follow the process in this document (or at Upgrade Abiquo 6.1.x to 6.2.x distributed by servers

Upgrade Abiquo packages
Run the guestpasswordmigrator
Upgrade mariadb on the main DB and watchtower DB
Apply the guestpasswords.sql file to the main DB
For Galera clusters, update the cluster details for the database connection
To display cost-usage reports, run regenerate billing

Minor version upgrade table

From version	To version	Upgrade type	Notes
6.1.0	6.1.1	Standard	See Standard Abiquo minor or patch version update
6.1.1	6.1.2	Standard + Guacamole	See Standard Abiquo minor or patch version update and Upgrade Guacamole server
6.1.2	6.1.3	Standard	See Standard Abiquo minor or patch version update
6.1.3	6.1.4	Standard	See Standard Abiquo minor or patch version update

2. Warnings and notices

Before you begin, contact Abiquo Platform and Customer Success department to obtain your credentials because Abiquo YUM repositories require a login.

Major upgrade

The upgrade to Abiquo 6.2.0 is a major upgrade with upgrades of third-party software packages that are critical platform dependencies

You must make snapshots of ALL servers before you start the upgrade

The upgrade will overwrite lang_en_US_labels.json. If you have customized labels or translations, back them up before the upgrade and restore them afterwards.

SAML upgrade

The upgrade will overwrite the SAML login configuration for multiple IdPs. If you use SAML with multiple IdPs, back up the configuration files before the upgrade and add the multiple IdPs afterwards accordingly. See Restore SAML security beans after upgrade.
For Abiquo 6.0.0+, you must configure the SAML maximum authentication age property or SAML will not initialize

3. Prevent cloud users from performing VM operations

In the UI in the Infrastructure view, select each physical machine and click Disable
Using the API, set the state of each physical machine to DISABLED

4. Check for operations in progress on the platform

Before you shut down the platform servers, check that no operations are in progress.

Check that the Abiquo RabbitMQ queues are empty on the Abiquo Monolithic Server, Abiquo Server or Datanode server

The number of messages in all queues must be 0.

# rabbitmqctl list_queues messages name

# rabbitmqctl list_queues messages name
Listing queues ...
0	abiquo.am.notifications
0	abiquo.bpm.notifications
0	abiquo.datacenter.requests.ADatacenter.bpm
0	abiquo.datacenter.requests.ADatacenter.virtualfactory
0	abiquo.ha.tasks
0	abiquo.nodecollector.notifications
0	abiquo.pcrsync.messages
0	abiquo.pcrsync.parking-expect-no-consumers
0	abiquo.scheduler.fast.requests
0	abiquo.scheduler.requests
0	abiquo.scheduler.slow.requests
0	abiquo.tracer.traces
0	abiquo.virtualfactory.notifications
0	abiquo.virtualmachines.definitionsyncs
0	abiquo.vsm.eventsynk
...done.

On the V2V Server, check for any active conversions by checking for the V2V or Mechadora processes
```
$ ps aux | grep v2v
$ ps aux | grep mechadora
```

When user VM operations are blocked and all of the above checks show that no tasks are running, it is safe to halt the platform.

5. Stop platform services

This section describes how to stop platform services on all servers.

If there are operations in progress, DO NOT STOP the platform services because this can cause serious issues with your platform.
See Check for operations in progress on the platform and wait for all operations to complete

To stop platform services:

Stop the API on the API server or monolithic server
```
systemctl stop abiquo-tomcat
```
Stop the UI on the API server or monolithic server or dedicated UI server
```
systemctl stop httpd
```
Stop remote services server
```
systemctl stop abiquo-tomcat
```
V2V Server
You do not need to stop anything because the BPM remote service is run on-demand only

Stop monitoring server

systemctl stop abiquo-delorean
systemctl stop abiquo-emmett
systemctl stop kairosdb
systemctl stop cassandra

On the monitoring server, check if Cassandra is really dead
```
ps auwx | grep cassandra
```
Get the process number for Cassandra (the first number in the output of the previous command), and kill it. In this example, Cassandra is process 12345.
```
kill -9 12345
```

All processes on platform servers should now be halted.

6. Back up the main platform elements

To perform a basic backup of the platform, run the following backups:

Before you begin, stop platform services, and check you have enough space on your destination systems.

# On DB server, back up the Abiquo MySQL DBs
mysqldump --routines --triggers kinton            > kinton.sql-$(date +%Y%m%d_%H%M%S)
mysqldump --routines --triggers kinton_accounting > kinton_accounting.sql-$(date +%Y%m%d_%H%M%S)

# On the Monitoring server, back up Watchtower DB
mysqldump --routines --triggers watchtower            > watchtower.sql-$(date +%Y%m%d_%H%M%S)

# On the Abiquo API Server or UI server, back up the UI
tar cvfz /var/www/html/ui.tgz-$(date +%Y%m%d_%H%M%S) /var/www/html/ui

# If you are using SAML authentication with multiple IdPs, on ALL Abiquo API Servers, back up this file
cp 
/opt/abiquo/tomcat/webapps/api/WEB-INF/classes/springresources/security/saml/security-saml-generated-beans.xml /opt/abiquo/tomcat/webapps/api/WEB-INF/classes/springresources/security/saml/security-saml-generated-beans.xml-$(date
 +%Y%m%d_%H%M%S)

# Copy the api.xml file to back up the database connection details
cp /opt/abiquo/tomcat/conf/Catalina/localhost/api.xml /opt/abiquo/api.xml-$(date+%Y%m%d_%H%M%S)

# On ALL servers, back up the /opt/abiquo folder
tar cvfz /opt/abiquo.tgz-$(date +%Y%m%d_%H%M%S) /opt/abiquo

# On Abiquo Monolithic or API Server, Remote Services, or Datanode, back up Redis
redis-cli save
cp -a /var/lib/redis /var/lib/redis-$(date +%Y%m%d_%H%M%S)

7. Make snapshots and backups of all platform servers

This is a major upgrade, so we recommend that you make a snapshot and/or a full backup of your platform servers.

8. Prepare yum repositories for 6.2 or 6.2.x

Check that you have the repository URL and credentials

On all Abiquo Servers, such as Abiquo API, Remote Services, Watchtower monitoring.

Install release package

To upgrade to a version with a patch number of zero, for example, version 6.2.0
1. Remove the previous version Abiquo release packages.
```
yum remove 'abiquo-release-*'
```
2. Find the abiquo-release-ee package for your version in the list of available versions
3. Install the release package.
  For Abiquo 6.2.0, the command would be similar to the following:
```
yum localinstall http://usr:passwd@mirror.abiquo.com/el7/6.2/os/x86_64/abiquo-release-ee-6.2.0-AAAAAAAAAAAA.el7.noarch.rpm
```
  For Abiquo 6.2.1, the release package would be in the format:
```
http://usr:passwd@mirror.abiquo.com/el7/6.2/updates/x86_64/abiquo-release-ee-6.2.1-BBBBBBBBBBBB.el7.noarch.rpm
```
4. For major versions, disable the updates repo. See https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/6/html/deployment_guide/sec-managing_yum_repositories

Prepare yum repositories for 6.2.x (minor version)

Check that you have the repository URL and credentials
To upgrade to the latest version with a patch number that is not zero, for example, version 6.2.x, enable both repositories:
```
yum-config-manager --enable abiquo-base
yum-config-manager --enable abiquo-updates
```
Optionally add your username and password to the Abiquo repos
```
yum-config-manager --save --setopt=abiquo-*.username=MYUSERNAME
yum-config-manager --save --setopt=abiquo-*.password=MYPASSWORD
```
Don't forget to use a backslash to escape any shell special characters. For more details, see https://www.oreilly.com/library/view/learning-the-bash/1565923472/ch01s09.html
Clean yum and make cache
```
yum clean all && yum makecache
```
If you did not make snapshots of all servers already, then you could do this now.

9. Uninstall Docker

To avoid conflicts in the install, on each Remote Services server, manually uninstall Docker.

yum uninstall docker

10. Upgrade packages on ALL servers

These instructions are for monolithic, distributed, and HA environments.

Check in your RS server(s) if there is an NFS shared folder for the NARS results (related to the Abiquo configuration property abiquo.nars.async.fileresults.path):

$ mount | grep -i "nfs\|results" | grep -v sunrpc
10.60.37.87:/abq-pro-nfs on /opt/abiquo/results-nars type nfs4 (rw,nosuid,nodev,noexec,relatime,sync,vers=4.1,rsize=1048576,wsize=1048576,namlen=255,hard,proto=tcp,timeo=600,retrans=2,sec=sys,clientaddr=10.60.37.77,local_lock=none,addr=10.60.37.87,user)

Unmount the previous shared folder if you have it mounted:
```
sudo umount /opt/abiquo/results-nars
```
Update all packages:
```
yum clean all && yum makecache && yum update 
```
MariaDB update will fail. We will update it manually later
Mount the shared folder from the second step again.
```
sudo mount -a
```
The Abiquo services must run as the tomcat user (not root), so set the required permissions and enforce the use of the package configuration files.
If you have a MONOLITHIC SERVER do all of the following steps on the Monolithic server
1. On Abiquo server and remote services
```
chown -R tomcat /opt/abiquo
```
2. On the remote services with appliance manager and the V2V server (i.e. servers that mount the NFS repository)
```
chown -R tomcat /opt/vm_repository
chmod -R a+r /opt/vm_repository
```
3. On the V2V server, check the /etc/sysconfig/abiquo/ec2-api-tools file exists.
  The file must contain the following configuration. If the file does not exist, create it and add this configuration.
  For CentOS 7
```
EC2_HOME=/opt/aws
```

11. Run the guest password migrator

Download and install the guestpasswordmigrator package

Run the tool to migrate the guest passwords of the current VMs to a new column that will be added in 6.2.0.

The tool requires access to the kinton database and to the API Redis

Usage:

--jdbc-url VAL    : Replace VAL with Kinton JDBC URL including user and password
--output-file VAL : Replace VAL with the output file (by default: 'guestpasswords.sql') 
--redis-host VAL  : Redis host to connect
--redis-port N    : Redis port to connect (by default: 6379)

For example:

java -jar gpmigrator.jar --jdbc-url="jdbc:mariadb://localhost:3306/kintonuser=root&password=root" --redis-host=localhost

Save the guestpasswords.sql file and run it after you update the database with abiquo-db.

12. Upgrade MariaDB for Abiquo 6.2.0

On all database servers, including the Watchtower server, upgrade MariaDB

rpm --nodeps -ev MariaDB-server-10.4.10-1.el7.centos.x86_64
yum install MariaDB-server
service mariadb start
mysql_upgrade

13. Update the Abiquo databases

Check that your hostname is in your DNS or in your /etc/hosts file

Upgrade the Abiquo API databases

abiquo-db [-h DB hostname] [-P DB port] [-u user] [-p password] update

If the Liquibase update fails with a message similar to the following:

Liquibase update Failed: Validation Failed:
1 change sets check sum
src/X.X.X-XX/kinton-X.X.X.xml::ABICLOUDPREMIUM-XXXX-XxxxxxxxXXxXxxxxxxXxxxxx::XXXXXXXXX is now: 7:ee2fa6e058ec76c7abf801567898917d
For more information, use the --logLevel flag

Do the following steps

Clear the database checksums
```
abiquo-db clearCheckSums
```
Retry the above abiquo-db update command.

In MariaDB, for Abiquo 6.2.0, run the SQL file output from the guest password migrator script (with the appropriate user and credentials)
```
mysql kinton < guestpasswords.sql
```
To upgrade the Abiquo Watchtower database, on the monitoring appliance, run the command below:
```
watchtower-db [-h DB hostname] [-P DB port] [-u user] [-p password] update
```

14. Upgrade additional elements

By default, you will find the upgrade scripts (e.g. for Redis definitions) on the Abiquo Server under the folder: /usr/share/doc/abiquo-redis/redis/

For each upgrade step, run the Redis database script to remove old VSM definitions, which can be found in the 4.2.3 subfolder

On remote services server:

# cd /usr/share/doc/abiquo-redis/redis/
# bash ./4.2.3/00-old-vsm-definitions.sh

For Abiquo 6.2.0+, update the database connector configurations

On the Abiquo API Server, edit /opt/abiquo/tomcat/conf/Catalina/localhost/api.xml
If your database is on the Abiquo Server or a single server
1. For the database connector, remove jdbc:mysql://dbhost and replace with jdbc:mariadb:${DBHOST}

If you are using a separate database cluster:

Add the Galera configuration to the database connector (to replace jdbc:mysql://dbhost...)

jdbc:mariadb:loadbalance://address=(host=${DBMAIN})(port=3306)(type=master),
        address=(host=${DBR1})(port=3306)(type=slave),
        address=(host=${DBR2})(port=3306)(type=slave)/kinton

On the Watchtower server, edit the emmett.conf and delorean.conf files at:
```
/etc/abiquo/watchtower/delorean.conf
/etc/abiquo/watchtower/emmett.conf
```
1. From the connection details, remove jdbc:mysql: and replace with jdbc:mariadb:
2. Add your Galera configuration if your monitoring DB is in a cluster

15. Configure Abiquo after the upgrade

Before you start the Abiquo tomcat server, add Abiquo configuration properties to the abiquo.properties file.
By default the abiquo.properties file is found in the /opt/abiquo/config/ folder.
See Changes to Abiquo configuration properties
Configure the user interface. The default UI location is /var/www/html/ui.
Optional: Add custom labels and translations in the lang_xx_XX_custom.json files in the lang folder
Add custom configuration to client-config-custom.json. See Configure Abiquo UI and Changes to UI configuration
If your API is not in the same domain as the UI, set the API endpoint pointing to your Abiquo API server:
```
{
    "config.endpoint": "http://myAPIserver/api"
}
```
SAML: If you are using SAML with multiple IDPs, restore the configuration as described at Restore SAML security beans after upgrade.
Abiquo 6.2.0 updates Java and other packages, so restore your certificates. To do this, you can follow the steps at Update certificates in your Abiquo environment.

16. Start Abiquo server and services

To start the Abiquo platform servers and services, do these steps:

On the Abiquo server, restart the HTTP daemon to refresh the user interface files, and bring up the Tomcat server.
```
service httpd start
service abiquo-tomcat start
```
On the Remote services server, start the Tomcat server
```
service abiquo-tomcat start
```
On the Monitoring server: start the Cassandra service
```
sudo service cassandra start
```
WAIT about 5 minutes until the service is up and running
Start the KairosDB service
```
sudo service kairosdb start
```

Start the other services in this order

sudo service abiquo-emmett start
sudo service abiquo-delorean start

On the V2V server: restart the Tomcat server:
```
service abiquo-tomcat restart
```

Finally, in Abiquo, UI

Re-enable the physical machines!
In Abiquo 6.2.0, to activate the cost usage reports, regenerate billing

After the upgrade, to prevent glitches in the UI, clear your browser cache