Upgrading in a High Availability Environment

The upgrade to a cluster environment is first performed on the node where MySQL is active. The steps are then repeated on the other node.

Before you begin the upgrade, follow the backup steps described in Upgrading: Requirements to ensure easy rollback in case there are any issues.

Check the cluster manager status to locate the active node:

$ /opt/aspera/acm/bin/acmctl –i
Checking current ACM status...
Aspera Cluster Manager for Orchestrator - status
------------------------------------------
Local hostname:         orchestrator1
Active node:            orchestrator1 (me)
Status of this node:    active
Status file:            current
Disabled globally:      no
Disabled on this node:  no

In the above STDOUT, the orchestrator1 (active) node has MySQL running.

Back up important files.
On each node, copy the files below to a safe location (for example, /tmp) before the upgrade.
```
/opt/aspera/orchestrator/config/orchestrator.yml
/opt/aspera/orchestrator/config/orchestrator-license*
/opt/aspera/orchestrator/config/database.yml
```
Any custom files, like the ones below, should also be copied and restored after the upgrade.
```
/opt/aspera/orchestrator/public/images/aspera_logo_simple.jpg
/opt/aspera/orchestrator/public/stylesheets/aspera.css
```
On both Orchestrator instances, disable ACM.
```
$ /opt/aspera/acm/bin/acmctl -d
```
Stop Orchestrator services or all Aspera services on both instances.
Important: To avoid any issues with installation, be sure to run the asctl command applicable to your current setup:
- If the version of the Aspera Common Components ("Common") installed with your current Orchestrator setup is the same as the Common required to install the new version of Orchestrator (for example, Orchestrator v. 2.7.0, v. 2.7.1 and v. 3.0.1 all use Common 1.2.19), run the following command:
```
$ asctl orchestrator:stop
```
- If the version of Common installed with your current Orchestrator setup is a lower version than the Common required to install the new version of Orchestrator, run the following command:
```
$ asctl all:stop
```
Upgrade Orchestrator.
For both instances, follow the procedure in one of the following topics, depending on the Orchestrator version prior to upgrade:
Note: Be sure to follow the additional step in the upgrade procedure—for high availability installation only—that turns off the MySQL, Apache, and Orchestrator services after upgrading the Aspera Common Components.
Copy the following files from the backup location (for example, /tmp) to the original locations on both instances.
- Copy orchestrator.yml, orchestrator-license*, and database.yml to the following directory:
```
/opt/aspera/orchestrator/config/
```
- If found, copy aspera_logo_simple.jpg to the following:
```
/opt/aspera/orchestrator/public/images/
```
- If found, copy aspera.css to the following:
```
/opt/aspera/orchestrator/public/stylesheets/
```
Ensure that the contents of the following files are identical.
```
/opt/aspera/orchestrator/config/database.yml  
/opt/aspera/var/config/orchestrator/database.yml
```
If the files are not identical, use the values in the following file:
```
/opt/aspera/var/config/orchestrator/database.yml
```
Enable ACM on both instances.
```
$ /opt/aspera/acm/bin/acmctl -e
```
ACM will start MySQL, Apache and Aspera Orchestrator on one instance and Apache and Orchestrator on another instance.
On one instance only, upgrade the plugins as necessary, according to the instructions in Upgrading Plugins and Portlets After an Upgrade of Orchestrator, below.
On both instances, reload the plugins and execute force maintenance.
Click Engine > Plugins > Reload Plugins, and then click Engine > Processes > Force Maintenance to set the new code.

Upgrading a Single Node from Orchestrator 2.3.5+ to the Current Release

The procedure in this topic is only for those upgrading from Orchestrator 2.3.5 + to the current release.

Note: Because it is likely that the Aspera Common Components installed with earlier versions of Orchestrator are incompatible with the current released version, IBM Aspera recommends that you upgrade the Aspera Common Components before upgrading (instructions for this are given in Step 5).

Before upgrading Orchestrator, review product release notes.

Aspera strives to maintain compatibility from one release to the next, but sometimes we must make changes that affect a small number of customers. Review the release notes for all Orchestrator versions that have been released since your current version. In particular, the Breaking Changes section highlights changes that may require you to adjust your workflow, configuration, or usage. These issues may impact your new installation.
Follow the backup steps described in Upgrading: Requirements to ensure easy rollback in case there are any issues.
After upgrading, previously installed releases of Aspera Orchestrator are still present in /opt/aspera and can be used for rollback operations. For example:
```
/opt/aspera/Orchestrator_version/
```
Download the installation files for the new release.
1. Go to the Aspera downloads website, http://downloads.asperasoft.com/en/downloads/27.
2. Using your login credentials, download both installers:
  - version - Linux RPM x86_64 (Aspera Orchestrator)
  - versionCom - Linux RPM x86_64 (Aspera Common Components)
  After download, the installers appear with the following formats (aspera-common is the Aspera Common Components):
```
aspera-orchestrator-version-0.x86_64.rpm
aspera-common-version-0.x86_64.rpm
```
3. Save the installers to the machine where Orchestrator is to be upgraded.
Stop Orchestrator services or all Aspera services.
To avoid any issues with installation, be sure to run the asctl command applicable to your current setup.
- If you don't need to upgrade the Aspera Common Components ("Common"), run this command:
```
asctl orchestrator:stop
```
- If you must upgrade Common, run this command:
```
asctl all:stop
```

Upgrade the Aspera Common Components, if needed.

# rpm -Uvh aspera-common-version-0.x86_64.rpm
Preparing...                          ################################# [100%]
Updating / installing...
1:aspera-common-version-0    ################################# [ 50%]
Cleaning up / removing...
2:aspera-common-version-0    ################################# [100%]

Upgrade Orchestrator.

# rpm -Uvh aspera-orchestrator-version-0.x86_64.rpm 
Preparing... ########################################### [100%]
1:aspera-orchestrator    ########################################### [100%]

(High availability upgrade, only) If you are upgrading in a high availability (HA) environment that uses ACM software, turn off the MySQL, Apache, and Orchestrator services with the chkconfig command.
This step is necessary for ACM to function properly.
```
# chkconfig aspera_mysqld off
# chkconfig aspera_httpd off
# chkconfig AsperaOrchestrator off
```
Before completing the upgrade, confirm that the orchestrator symlink still exists.
If the symlink does not still exist, recreate it with the commands in "Setting up Mount Points for Shared Orchestrator /var Data," step 2.
Below is an example of the symlink that you need, and how to locate it.
```
# pwd
/opt/aspera/var/config
# ls -all
lrwxrwxrwx  1 root root   58 Aug 30 10:13 orchestrator -> /mnt2/ha_orchestrator/orchestrator/var/config/orchestrator
```
Complete the upgrade by setting up Orchestrator.
```
# asctl orchestrator:setup
```
A Ruby version selection prompt appears:
```
Orchestrator
Use Ruby 2.3.0 (y/n)? (current: y) 
```
Enter "y" to use Ruby 2.3.0 in the installation.
Note: If you select "n" at this prompt, Orchestrator will use Ruby 1.8.7 for the installation. You will still have access to all Orchestrator features; however, you will not experience the improved engine performance supported by Ruby 2.3.0.

Important: When upgrading from an older version of Orchestrator (which runs Ruby 1.8.7) to Orchestrator 3.0.2, if you choose "y" for "Use Ruby 2.3.0 (y/n)?" and you have work orders with a current status of "In Progress", those work orders will fail after upgrade and you will need to restart any asynchronous steps. (This issue is caused by the older and newer Rails versions handling ActiveRecord in different ways).
If for any reason it will not be possible to restart the asynchronous steps after upgrade, you must select "n" for"Use Ruby 2.3.0 (y/n)?" and continue to use Ruby 1.8.7 with Orchestrator 3.0.2.
Check the following directory if there are capsules present in the folder.
```
/opt/aspera/var/config/orchestrator/capsules/
```
Review the current release notes and remove any capsules that are no longer needed. Contact Technical Support for any questions regarding the handling of capsules after an upgrade.

Upgrading Plugins and Portlets After an Upgrade of Orchestrator

During an upgrade, plugins are not upgraded automatically and new portlets are not enabled by default; the steps below will allow you to update these as needed.

Go to Engine > Plugins and click Available Plugins to see the newer plugins.
Each plugin contains a Revision History screen providing details about the newer plugin. After reviewing the revision history, upgrade the plugin and force maintenance. For more details on plugin installation and upgrading, refer to the Aspera Orchestrator User Guide.
Find out if any new plugins are not already enabled by selecting Not enabled only, and enable them if necessary.

Note: In a production system, upgrade the new plugins individually only when necessary (compare the previous version with the current released version). It is advisable to test them in pre-production first to make sure that the new plugins operate well with the existing workflows.
Click Engine > Plugins > Reload Plugins, and then click Engine > Processes > Force Maintenance to set the new code.
If the new portlets are not enabled, and they are needed, click Engine > Portlets > Enable all.
Test your workflows to make sure they function properly after the upgrade.