Edit

Upgrade from v9.2.0 to v9.2.x

Overview

The guide describes the steps to upgrade SPA from v9.2.0 to v9.2.x.

Note that the following examples are provided for target SPA 9.2.1. If you want to upgrade SPA to 9.2.2 or SPA 9.2.3, replace the version in all packages and commands accordingly.

Prerequisites

• You have WorkFusion SPA 9.2.0 installed.
• You have downloaded Workfusion SPA 9.2.x package workfusion-full-package-9.x.x.0-2963.tar.gz to DB, APP, AutoML Master, AutoML Agent(s), OCR, and APM servers (assume that package is in /tmp/workfusion-full-package-9.x.x.0-2963.tar.gz).
• All actions for upgrade form 9.2.0 to 9.2.x must be performed as <WF_USER>. The Root user is not required.

Preparation

Unarchive 9.2.x installer on all servers

Adjust the INSTALL_DIR variable according to your environment and run as <WF_USER> on all Linux servers (DB, APP, OCR, APM, AutoML Master, AutoML Agent(s)).

$ export INSTALL_DIR=/opt/workfusion    ## the value of "install_dir" setting from config.yml used in 9.2.0 installation

$ mkdir $INSTALL_DIR/wf_installer_921
$ tar -xzvf /tmp/workfusion/workfusion-full-package-9.2.1.0-2963.tar.gz --strip 1 -C $INSTALL_DIR/wf_installer_921

Prepare certificates and configs for 9.2.x installation

1. Copy certificates and configs used originally during 9.2.0 installation to 9.2.x package directory on DB server. They can be found on DB server (they exist only on DB server) in <INSTALL_DIR>/distr/latest/directory. Run as <WF_USER> on DB server:

   $ cd $INSTALL_DIR/wf_installer_921
   $ cp -r $INSTALL_DIR/distr/latest/certificates .
   $ cp $INSTALL_DIR/distr/latest/config_overrides.yml ./config_overrides.yml
   $ cp $INSTALL_DIR/distr/latest/secrets_overrides.yml ./secrets_overrides.yml
   

2. Copy the same certificates and configs from DB server to APP, OCR, APM, AutoML Master, AutoML Agent(s) servers to the same location.

   The example below describes how to transfer required files using Python (the simplest way without any prerequisites, assuming there is network availability between DB server and other linux servers of the environment).

   1. Create wf_configs.tar.gz archive of configs and certificates on DB server and make it temporarily available for download over HTTP over port 9999 (you can choose any free port):

   cd $INSTALL_DIR/wf_installer_921
   tar czvf wf_configs.tar.gz certificates config_overrides.yml secrets_overrides.yml
   
   ## This will make all content of $INSTALL_DIR/wf_installer_921 directory on DB server downloadable over HTTP over 9999 port (you can choose any free port):
   python -m SimpleHTTPServer 9999
   

   1. Log in over SSH to other linux servers of the environment, download wf_configs.tar.gz archive from DB server, and extract it. Run as <WF_USER> on APP, ** OCR, APM, AutoML Master, AutoML Agent(s) servers:

   export DB_HOSTNAME=db.example.com     ## the value of "db_hostname" setting from config.yml used in 9.2.0 installation
   
   cd $INSTALL_DIR/wf_installer_921
   wget http://$DB_HOSTNAME:9999/wf_configs.tar.gz -O wf_configs.tar.gz
   tar xzvf wf_configs.tar.gz -C /opt/workfusion/wf_installer_921
   

   2. On DB server, press Ctrl + C to stop file sharing over Python HTTP server.

Get decryption password for secrets_overrides.yml file

The file secrets_overrides.yml which we just transferred is encrypted with ansible vault. This file contains sensitive settings used originally during 9.2.0 installation.

You have to tell the 9.2.x installer how to decrypt this file during installation and read the settings. The decryption password is stored securely in Hashicorp Vault service on DB server. Run as <WF_USER> on DB server to get decryption password:

$ cd $INSTALL_DIR/wf-sec-storage
$ ./loader.sh ansible review | grep ansible_vault_password

## The output should be similar to this:
[INFO ] ansible_vault_password : JHYltHft1AnlwPg

Copy the decryption password (in the example above it is JHYltHft1AnlwPg) somewhere (e.g. write it to some file), or remember it. You will be asked for this password later on each server, right after running installation command.

The decryption password will be changed to a new value automatically after upgrade to 9.2.x. Thus, if you need to upgrade from 9.2.1/9.2.2 to 9.3, or 9.4, you'll have to get a new decryption password using the same way.

Stop services on all servers

Run on APP, OCR, APM, AutoML Master, AutoML Agent(s), and DB servers (DB server should be the last server).

wfmanager stop all

Prepare license file on APP server

The license file must be present in the $INSTALL_DIR/wf_installer_921/ directory on APP server. Run on APP server:

cd $INSTALL_DIR/wf_installer_921
cp $INSTALL_DIR/workfusion/conf/license.properties .

Upgrade steps

Run as <WF_USER> on DB, APP, OCR, APM, AutoML Master, AutoML Agent(s) servers (DB server should be upgraded first).

## on all servers
$ cd $INSTALL_DIR/wf_installer_921

## on DB server
$ ./install.sh install db -e @config_overrides.yml -e @secrets_overrides.yml -e passwords_check=false --ask-vault-pass
$ ./install.sh check db -e @config_overrides.yml -e @secrets_overrides.yml -e passwords_check=false --ask-vault-pass
 
## on APP server
$ ./install.sh install app -e @config_overrides.yml -e @secrets_overrides.yml -e passwords_check=false --ask-vault-pass
$ ./install.sh check app -e @config_overrides.yml -e @secrets_overrides.yml -e passwords_check=false --ask-vault-pass
 
## on OCR server
$ ./install.sh install ocr -e @config_overrides.yml -e @secrets_overrides.yml -e passwords_check=false --ask-vault-pass
$ ./install.sh check ocr -e @config_overrides.yml -e @secrets_overrides.yml -e passwords_check=false --ask-vault-pass
 
## on APM server
$ ./install.sh install apm -e @config_overrides.yml -e @secrets_overrides.yml -e passwords_check=false --ask-vault-pass
$ ./install.sh check apm -e @config_overrides.yml -e @secrets_overrides.yml -e passwords_check=false --ask-vault-pass
 
## on AutoML Master server
$ ./install.sh install vds-master -e @config_overrides.yml -e @secrets_overrides.yml -e passwords_check=false --ask-vault-pass
$ ./install.sh check vds-master -e @config_overrides.yml -e @secrets_overrides.yml -e passwords_check=false --ask-vault-pass
 
## on AutoML Agent(s) server(s)
$ ./install.sh install vds-slave -e @config_overrides.yml -e @secrets_overrides.yml -e passwords_check=false --ask-vault-pass
$ ./install.sh check vds-slave -e @config_overrides.yml -e @secrets_overrides.yml -e passwords_check=false --ask-vault-pass

After running each command, you'll be asked to enter the Vault password. The prompt looks as follows:

$ ./install.sh install db -e @config_overrides.yml -e @secrets_overrides.yml -e passwords_check=false --ask-vault-pass
=> Running 'flat:precheck' tasks
Vault password:

At this point, paste (Ctrl + V) the password that you saved on step 3.

• When you run the ./install.sh install command, the Vault password will be asked twice: the first time, right after you press Enter, and second time–in about 20 seconds. You must paste it again.
• When you run the ./install.sh check command, the Vault password will be asked just once.

Post-upgrade steps

You can review difference between old configuration files and new in the changes log: /distr/latest/diff_changes_.log

If needed, follow the steps from the Post-installation guide to make sure the environment works properly.