Edit

Upgrade from v9.2.0 to v9.4.0

Overview

The guide describes the steps for in-place SPA upgrade from 9.2.0 to 9.4.x.

Prerequisites

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

Preparation

Unarchive 9.4.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.4.x.0-2963.tar.gz --strip 1 -C $INSTALL_DIR/wf_installer_921

Prepare certificates and configs for 9.4.x installation

1. Copy certificates and configs used originally during 9.2.0 installation to 9.4.x package directory on DB server. They can be found on DB server (they exist only on DB server) in the <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 the 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
   

2. Log in over SSH to other Linux servers of the environment, download the wf_configs.tar.gz archive from DB server, and extract it. Run as <WF_USER> on APP, OCR, APM, AutoML Master, and 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
   

3. Press Ctrl + C on DB server to stop file sharing over Python HTTP server.

Get decryption password for secrets_overrides.yml file

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

You need to tell 9.4.x installer how to decrypt this file during the 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 the 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 the installation command.

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

Stop the 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 should be present in the $INSTALL_DIR/wf_installer_921/ directory on APP server. Run under on APP server:

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

Upgrade steps

1. 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
   

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

   ./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:
   

3. Paste (Ctrl + V) the password 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 should 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 changes log: /distr/latest/diff_changes_.log

Follow the steps from the Post-installation guide to make sure the environment works properly.