Installing an Upgrade or Hotfix

Detailed information how to upgrade IBM Financial Services Workbench.

This will guide you through the upgrade process of IBM Financial Services Workbench .

The upgrade is similar to the Installation Process, except that backups should be created, configuration files do not need to be created from scratch, and version-specific configuration and migration steps must be performed according to the Upgrade Notes.

Here's the basic process for installing a new Upgrade or Hotfix version:

Check Prerequisites
Obtain the installation package
Configure the new version
Install the Upgrade
Perform Post-Upgrade tasks

Check Prerequisites

Before you upgrade the IBM Financial Services Workbench, ensure that the following tasks are complete:

Review the Upgrade Notes

Please note the version-specific upgrade instructions in the Upgrade Notes. It contain important information about the version-specific changes and the necessary changes to be made when you upgrade to the new version. Also check the Upgrade notes of all version numbers between the currently installed version and the version you are about to install.
Verify System Requirements

If you plan to upgrade IBM Cloud Pak for Data or a third-party component along with the upgrade, please check compatibility with System Requirements and inspect the Installing Third-Party Components section before upgrading to the new version. It is recommended that you upgrade only on the basis of the changes required for the upgrade and re-run the installation process separately if other configuration changes require it.
Provide access to the configuration files of the last installation

This guide assumes that you have read access to the folder containing the customized configuration files that were used for the currently installed version. Use the backup of the custom configuration files that was created according to the Backup the configuration files section just before the last installation was performed. For example in folder ~/install/sssob_2.2.2/ssob-install/deployments/configs.bak/.
Obtain account with sufficient permissions

Setting up Cluster-wide resources requires an account in the Cluster administrator role, and upgrading to a new version by running the install.sh script requires the project administrator role for the project where you previously installed IBM Financial Services Workbench.

Obtain the installation package

To obtain files required for upgrading IBM Financial Services Workbench:

Go to Passport Advantage Online.
Search for Financial Services Workbench for Cloud Pak for Data
Download the new version you want to upgrade to, e.g. ssob-2.8-ibm-openshift-4.6-cpd-installations.tgz.

Unpack the installation file on the computer from which the installation commands are to be executed:

$ INSTALLDIR=~/install/
$ mkdir ${INSTALLDIR}
$ cd ${INSTALLDIR}
$ tar xzvf ssob-2.8-ibm-openshift-4.6-cpd-installations.tgz     
$ mv ssob-2.8-ibm-openshift-4.6-cpd-installations ssob_2.8   
$ cd ${INSTALLDIR}/ssob_2.8

Important: Make sure that the configuration files in the ssob-install/deployments/configs folder that will contain the customized parameters for this installation are still accessible when upgrading to a newer version.

Note: The installation file is a self-contained package and contains all container images and associated resource files required for a new installation. This also applies to a hotfix release, but in the sense that it is exactly the same as the last minor stable release except for the fixes for which the hotfix was created.

Configure the new version

Unless required otherwise in the Upgrade Notes, the upgrade uses the same configuration files that were active when the last version was installed. Take the configuration files from the backup configuration directory of the last installation, e.g. ~/install/sssob_2.2.2/ssob-install/deployments/configs.bak/. and copy those files to the config folder of the version you are about to install, e.g. ~/install/ssob_2.8/ssob-install/deployments/configs/.

Customize the configuration files

Adjust the configuration to your needs based on the Upgrade Notes:

Tip:

Connect via scp to the server host and download the files to your local computer, for example:

$ scp user@remote_host:remote_file ~/remote_directory 
$ scp root@11.11.11.11:/root/install/ssob_2.8/ssob-install/deployments/configs/install_init_data.yaml /root/install

Locally edit your files and then connect via scp to the server host and upload each edited file, for example:

$ scp local_file user@remote_host:remote_file
$ scp install_init_data.yaml root@11.11.11.11:/root/install/ssob_2.8/ssob-install/deployments/configs/install_init_data.yaml

After transferring or editing the files, make sure that the file structure has not changed.

$ vimdiff /root/install/sssob_2.2.2/ssob-install/deployments/configs.bak/install_init_data.yaml configs/install_init_data.yaml
$ vimdiff /root/install/sssob_2.2.2/ssob-install/deployments/configs.bak/solution-designer-values.yaml configs/solution-designer-values.yaml
$ vimdiff /root/install/sssob_2.2.2/ssob-install/deployments/configs.bak/solution-hub-values.yaml configs/solution-hub-values.yaml

Backup the configuration files

CAUTION: The YAML files are processed and modified by the installation script. Therefore, after you have customized the files to your needs, you must backup those files before executing the installation script. This is especially important because these files must still be accessible for the next Upgrade.

Backup the following files:

install_init_data.yaml
install.yaml
solution-designer-values.yaml
solution-hub-values.yaml

For example:

$ cd ~/install/ssob_2.8/ssob-install/deployments
$ mv configs configs.bak
$ mkdir configs
$ cp ./configs.bak/* configs

Install the Upgrade

For detailed instructions, refer to the Installation Process. The installation of the new version during the upgrade is essentially the same as the initial installation. To illustrate the upgrade, the following sections provide examples of the commands required for the installation.

Before you begin

Make sure that docker is started and that you are logged into OpenShift as project / cluster admin.

$ oc login
$ systemctl start docker
$ cd ~/install/ssob_2.8

Step 1: Setup cluster-wide resources

Run the script ssob_admin_setup.sh with cluster-admin permissions in the project where the last version was installed , i.e. zen .

$ cd ssob-install/deployments
$ chmod +x ssob_admin_setup.sh
$ ./ssob_admin_setup.sh --accept_license --cpd_namespace=zen --external_address_image_registry=image-registry.apps.{your.domain.cloud}

Step 2: Installation of IBM Financial Services Workbench

Run the script ssob_install.sh with project-admin permissions in the project where the last version was installed.

$ cd ~/install/ssob_2.8/ssob-install/deployments
$ chmod +x ssob_install.sh
$ ./ssob_install.sh \
--accept_license \
--external_address_image_registry=image-registry.apps.{your.domain.cloud} \
--internal_address_image_registry=image-registry.openshift-image-registry.svc:5000 \
--cpd_namespace=zen \
--host_domain=apps.{your.domain.cloud} \
--helm-tls-ca-cert=~/install/ssob_2.8/zenhelm/ca.cert.pem \
--helm-tls-cert=~/install/ssob_2.8/zenhelm/helm.cert.pem \
--helm-tls-key=~/install/ssob_2.8/zenhelm/helm.key.pem

Step 3: Configuration of the installation

The Solution Designer and the Solution Hub will not work until the configuration via the K5 Configurator API has been done properly. If you are upgrading to version 2.5, you must configure this once.

CAUTION: If you upgrade to 2.5, you must keep your previous configuration available (see Checklist before configuration ) and use the K5 Configurator API to create the same configuration settings as before the upgrade.

Step 4: Validate the installation

The installation will finish with the message The script finished successfully. Make sure that the expected versions of Solution Designer and Solution Hub are deployed. Additionally check at least that the Solution Designer work as expected.

Troubleshooting

In case the installation failed, please check the log file /tmp/wdp.install.log and refer to the Troubleshooting section.

Perform Post-Upgrade tasks

Please refer to the Upgrade notes section. It contains additional necessary upgrade steps, especially migration instructions.

And validate the Solution Designer and Solution Envoy Web applications can be opened in the browser.