Upgrading

If you are currently on 4.0 then follow instructions from 'Upgrading to 4.1 from 4.0' but upgrade to 4.6 instead.

Otherwise, to upgrade to Transformation Advisor 4.6.0, you will need to switch the subscription channel. In the OpenShift UI, navigate to the Transformation Advisor Operator. Click on the Subscription tab and click to edit the v4.5 channel in the Update channel area. Select the v4.6 channel from the list of options. Allow Transformation Advisor several minutes to update.

If you are currently on 4.0 then follow instructions from 'Upgrading to 4.1 from 4.0' but upgrade to 4.5 instead.

Otherwise, to upgrade to Transformation Advisor 4.5.0, you will need to switch the subscription channel. In the OpenShift UI, navigate to the Transformation Advisor Operator. Click on the Subscription tab and click to edit the v4.4 channel in the Update channel area. Select the v4.5 channel from the list of options. Allow Transformation Advisor several minutes to update.

If you are currently on 4.0 then follow instructions from 'Upgrading to 4.1 from 4.0' but upgrade to 4.4 instead.

Otherwise, to upgrade to Transformation Advisor 4.4.0, you will need to switch the subscription channel. In the OpenShift UI, navigate to the Transformation Advisor Operator. Click on the Subscription tab and click to edit the v4.3 channel in the Update channel area. Select the v4.4 channel from the list of options. Allow Transformation Advisor several minutes to update.

If you are currently on 4.0 then follow instructions from 'Upgrading to 4.1 from 4.0' but upgrade to 4.3 instead.

Otherwise, to upgrade to Transformation Advisor 4.3.0, you will need to switch the subscription channel. In the OpenShift UI, navigate to the Transformation Advisor Operator. Click on the Subscription tab and click to edit the v4.2 channel in the Update channel area. Select the v4.3 channel from the list of options. Allow Transformation Advisor several minutes to update.

If you are currently on 4.0 then follow instructions from 'Upgrading to 4.1 from 4.0' but upgrade to 4.2 instead.

Otherwise, to upgrade to Transformation Advisor 4.2.0, you will need to switch the subscription channel. In the OpenShift UI, navigate to the Transformation Advisor Operator. Click on the Subscription tab and click to edit the v4.1 channel in the Update channel area. Select the v4.2 channel from the list of options. Allow Transformation Advisor several minutes to update.

If you are currently on 4.0 then follow the below steps:

1. Generate a new certificate using below openssl command.

   openssl req -newkey rsa:2048 -nodes -keyout private.pem -x509 -days 730 -out public.crt -subj "/C=IE/ST=Cork/L=Cork/O=IBM/CN=internal.ta.ibm.com" -addext "subjectAltName=DNS:ta-couchdb.<namespace>.svc,DNS:*.ta-couchdb.<namespace>.svc,DNS:*.ta-couchdb.<namespace>.svc.cluster.local,DNS:ta-couchdb.<namespace>.svc.cluster.local
    

2. Create key.p12(combined Keystore and Truststore) file.

   openssl pkcs12 -export -inkey private.pem -in public.crt -name default -out key.p12 -passout pass:plain-text-password
    

3. Encode newly generated files in base64 format.

   # base64 encode key.p12, private-base64, and public-base64
   
   # on Linux
     base64 -w 0 ./key.p12 > key-base64
     base64 -w 0 ./private.pem > private-base64
     base64 -w 0 ./public.crt > public-base64
   
   # on Mac
     base64 ./key.p12 > key-base64
     base64 ./private.pem > private-base64
     base64 ./public.crt > public-base64
    

4. Replace private-base64 and public-base64 in transformation-advisor-secret using OCP UI.

   Login to OCP -> Workloads -> Secrets -> select transformation-advisor-secret -> Edit Secret
   
   Replace ta_private_key with private-base64 value.
   Replace ta_public_key with public-base64 value.
    

5. Patch key.p12 using below command.

   oc patch secret transformation-advisor-secret -p '{"data": {"key.p12": "'$(cat key-base64)'"}}'
    

6. Upgrade TA to 4.1

7. Copy public.crt Transformation Advisor Instance.

Login to OCP -> Operators -> Installed Operators -> IBM Transformation Advisor -> Select Instance -> Edit TransAdv

Manually copy and paste public.crt value to authentication.tls.caCert. 
Remember the indentation is important. There are 2 extra spaces for each line of the cert than the line of `caCert`.

 

If you have already upgraded to 4.1 and if you see below errors in the server logs then perform all of the above steps except step 6 and restart all the pods.

⁃       Caused by: javax.net.ssl.SSLPeerUnverifiedException: Hostname ta-couchdb.<namespace>.svc not verified:
⁃       certificate: sha256/M3BRjmy3Pvd1eqQbCzKyeNbXAoNIaat71QoHzaNWR2Y=
 

There is no upgrade path to Transformation Advisor 4.0. We recommend that you upload your existing zip files again, or download the discovery tool and re-run it. If you have existing data that only exists in Transformation Advisor then you may wish to migrate your data. Further details on data migration can be found in our data migration section. Further details on uninstalling the old major version and installing the new one can be found in moving from 2.5.x to 3.0.x section

Back up your data before upgrading. See Backup/Export for more details.

To upgrade to Transformation Advisor 3.10.0, you will need to switch the subscription channel. In the OpenShift UI, navigate to the Transformation Advisor Operator. Click on the Subscription tab and click to edit the v3.9 channel in the Update channel area. Select the v3.10 channel from the list of options. Allow Transformation Advisor several minutes to update.

Back up your data before upgrading. See Backup/Export for more details.

To upgrade to Transformation Advisor 3.9.0, you will need to switch the subscription channel. In the OpenShift UI, navigate to the Transformation Advisor Operator. Click on the Subscription tab and click to edit the v3.8 channel in the Update channel area. Select the v3.9 channel from the list of options. Allow Transformation Advisor several minutes to update.

Back up your data before upgrading. See Backup/Export for more details.

To upgrade to Transformation Advisor 3.8.0, you will need to switch the subscription channel. In the OpenShift UI, navigate to the Transformation Advisor Operator. Click on the Subscription tab and click to edit the v3.7 channel in the Update channel area. Select the v3.8 channel from the list of options. Allow Transformation Advisor several minutes to update.

Back up your data before upgrading. See Backup/Export for more details.

To upgrade to Transformation Advisor 3.7.0, you will need to switch the subscription channel. In the OpenShift UI, navigate to the Transformation Advisor Operator. Click on the Subscription tab and click to edit the v3.6 channel in the Update channel area. Select the v3.7 channel from the list of options. Allow Transformation Advisor several minutes to update.

Back up your data before upgrading. See Backup/Export for more details.

To upgrade to Transformation Advisor 3.6.0, you will need to switch the subscription channel. In the OpenShift UI, navigate to the Transformation Advisor Operator. Click on the Subscription tab and click to edit the v3.5 channel in the Update channel area. Select the v3.6 channel from the list of options. Allow Transformation Advisor several minutes to update.

Back up your data before upgrading. See Backup/Export for more details.

To upgrade to Transformation Advisor 3.5.0, you will need to switch the subscription channel. In the OpenShift UI, navigate to the Transformation Advisor Operator. Click on the Subscription tab and click to edit the v3.4 channel in the Update channel area. Select the v3.5 channel from the list of options. Allow Transformation Advisor several minutes to update.

Back up your data before upgrading. See Backup/Export for more details.

To upgrade to Transformation Advisor 3.4.0, you will need to switch the subscription channel. In the OpenShift UI, navigate to the Transformation Advisor Operator. Click on the Subscription tab and click to edit the v3.3 channel in the Update channel area. Select the v3.4 channel from the list of options. Allow Transformation Advisor several minutes to update.

Back up your data before upgrading. See Backup/Export for more details.

To upgrade to Transformation Advisor 3.3.0, you will need to switch the subscription channel. In the OpenShift UI, navigate to the Transformation Advisor Operator. Click on the Subscription tab and click to edit the v3.2 channel in the Update channel area. Select the v3.3 channel from the list of options. Allow Transformation Advisor several minutes to update.

Back up your data before upgrading. See Backup/Export for more details.

To upgrade to Transformation Advisor 3.2.0, you will need to switch the subscription channel. In the OpenShift UI, navigate to the Transformation Advisor Operator. Click on the Subscription tab and click to edit the v3.1 channel in the Update channel area. Select the v3.2 channel from the list of options. Allow Transformation Advisor several minutes to update.

Back up your data before upgrading. See Backup/Export for more details.

How to upgrade:

To upgrade to Transformation Advisor 3.1.0, you will need to switch the subscription channel. This happens via Subscription tab in the IBM Transformation Advisor operator page. Click on v3.0 in the Update channel area and select v3.1. The product will automatically upgrade after saving the change of the channel. If you have edited the Transformation Advisor subscription to require manual approval for updates, you will have to confirm the upgrade.

Known issue:

There is a known issue when upgrading from 3.0.0 to 3.1.0 when Transformation is installed in a OpenShift cluster that does not support EgressNetworkPolicies. OpenShift clusters on IBM Cloud currently (correct at time of writing, April 2022) do not support EgressNetworkPolicies. In this case, the upgrade will not complete successfully. Follow this procedure to work around the issue:

1. Perform the upgrade by changing the subscription channel as normal.
2. After the operator has upgraded, the Transformation Advisor instance upgrade will stall. If you examine the logs of the operator pod, you will see a message like this:

   ...
   no matches for kind \"EgressNetworkPolicy\"
   ...
    

3. Go to the instance (Click into the Transformation Advisor operator, then on the Transformation Advisor tab, and then on the instance in the table)
4. Click the YAML tab and update the networkPolicy section to disable egress policies. The networkPolicy should look like the following when you are finished your update:

     networkPolicy:
       enabled: true
       egress:
         enabled: false
    

5. Save the update and the upgrade should automatically continue and succeed.

There is no upgrade path to Transformation Advisor 3.0. We recommend that you upload your existing zip files again, or download the discovery tool and re-run it. If you have existing data that only exists in Transformation Advisor then you may wish to migrate your data. Further details on data migration can be found in our data migration section. Further details on uninstalling 2.5.X and installing 3.0.X can be found in moving from 2.5.x to 3.0.x section.

This is NOT an automatic upgrade as the channel for Transformation Advisor 2.5.0 is different from 2.4.4. Switching the channel happens via Subscription tab in the Transformation Advisor operator page. Click on v2.4 in the Update channel area and select v2.5. The product will automatically upgrade after saving the change of the channel. If you have edited the Transformation Advisor subscription to require manual approval for updates, you will have to confirm the upgrade.

This is an automatic upgrade by default. Unless you have edited the Transformation Advisor subscription to require manual approval for updates, Transformation Advisor will automatically update to version 2.4.4 from 2.4.3. If you have edited the Transformation Advisor subscription to require manual approval for updates, check the OpenShift UI for install plans requiring approval.

This is an automatic upgrade by default. Unless you have edited the Transformation Advisor subscription to require manual approval for updates, Transformation Advisor will automatically update to version 2.4.3 from 2.4.2. If you have edited the Transformation Advisor subscription to require manual approval for updates, check the OpenShift UI for install plans requiring approval.

If you have used the Transformation Advisor version 2.4.2 CASE installer to upgrade from version 2.3.x to version 2.4.2, then the upgrade to 2.4.3 will not work. In the OpenShift UI, the Operator upgrade will appear to be stuck in a Pending state. If you encounter this problem, and only if you have used the 2.4.2 CASE installer to upgrade from 2.3.4, you need to execute the following procedure to fix Transformation Advisor:

1. Delete the Transformation Advisor subscription

   oc delete subscription ibm-transformation-advisor -n <namespace>
    

2. Delete the Transformation Advisor CSV

   oc get csv -n <namespace>
    

   oc delete csv <csv-name1> <csv-name2> -n <namespace>
    

3. Patch the Transformation Advisor instance configuration with license type. Visit this location to find the correct value for your installation.

   oc patch transadvs.ta.ibm.com/ta -p '{"spec":{"license":{"aLicenseType": "IBM Transformation Advisor 2.4.2 (Evaluation) - L-NHON-BYPFMS"}}}' --type=merge -n <namespace>
    

4. Recreate the Transformation Advisor subscription.

   a. Save the following yaml to a file. Update the namespace as appropriate.

   ```bash {: codeblock}
   apiVersion: operators.coreos.com/v1alpha1
   kind: Subscription
   metadata:
     name: ibm-transformation-advisor
     namespace: <namespace>
   spec:
     channel: v2.4
     name: ibm-transformation-advisor
     installPlanApproval: Automatic
     source: ibm-transadv-catalog
     sourceNamespace: openshift-marketplace
    startingCSV: ta-operator.v2.4.3
   ```
    

   b. Apply the subscription.

   ```bash {: codeblock}
   oc apply -f <subscriptionfile.yaml>
   ```
    

In the Installed Operators Openshift UI, you should now see the 2.4.3 Transformation Advisor operator installs successfully, and after a number of minutes, the 2.4.3 instance will be available for use.

This is an automatic upgrade by default. Unless you have edited the Transformation Advisor subscription to require manual approval for updates, Transformation Advisor will automatically update to version 2.4.2 from 2.4.1. If you have edited the Transformation Advisor subscription to require manual approval for updates, check the OpenShift UI for install plans requiring approval.

This is an automatic upgrade by default. Unless you have edited the Transformation Advisor subscription to require manual approval for updates, Transformation Advisor will have automatically updated to 2.4.1 from 2.4.0. If you have edited the Transformation Advisor subscription, to require manual approval for updates, check the OpenShift UI for install plans requiring approval.

Transformation Advisor 2.4.X is delivered in the IBM Operator Catalog. For more information, see Planning. Transformation Advisor 2.3.X was delivered in the Red Hat catalog and is now deleted from it. Consequently, there is no direct upgrade path to Transformation Advisor 2.4.X. If want to upgrade from Transformation Advisor 2.3.X to 2.4.X, you have the following options:

• Option 1: If you have no customizations to the Transformation Advisor instance, and no requirement to keep data, then you can simply uninstall 2.3.X and install 2.4.X as described in the installation instructions.

  You can uninstall 2.3.X in the OpenShift UI as follows:

  1. Find the Transformation Advisor operator in the Installed Operators.
  2. Click through on the Transformation Advisor operator to find the instance. You will see the instance when you click the Transformation Advisor tab.
  3. Click on the kebab icon for the Transformation Advisor instance and select Delete TransAdv.
  4. Back on the Installed Operators page, click on the kebab icon for the Transformation Advisor operator and select Uninstall Operator.

• Option 2: Download the CASE installer for Transformation Advisor and install 2.4.X using the --upgrade option. This will preserve any customizations to the 2.3.X instance and your 2.3.X data. See the Installing using the CASE installer section in the installation documentation for more details.

  In case you have modified authentication.ocp.secretName value on install, you need to patch your secret before running the upgrade using following script:

  #!/bin/bash
  
  random_string(){
    rand=$(cat /dev/urandom | tr -dc 'a-zA-Z0-9' | fold -w ${1:-32} | head -n 1)
    echo -n $rand | openssl sha1 | sed 's/^.* //'
  }
  
  secret_name=<YOUR_SECRET_NAME>;
  
  NONADMINUSER=$( random_string | base64 )
  NONADMINSECRET=$( random_string | base64 )
  oc patch secret $secret_name -p '{"data":{"db_nonadmin_user": "'"$NONADMINUSER"'"}}' --type=merge
  oc patch secret $secret_name -p '{"data":{"db_nonadmin_secret": "'"$NONADMINSECRET"'"}}' --type=merge
  
   

• Option 3: Follow the manual instructions described here to keep your 2.3.X data.

  1. Backup your data from a previously installed version. See Backup and Restore document for your options for doing that.

  2. You can uninstall Transformation Advisor 2.3.x, while preserving the PersistentVolumeClaim that it uses. That PersistentVolumeClaim can then be used with you new Transformation Advisor 2.4.X install. Preserving the PersistentVolumeClaim is the easiest way to keep your data when upgrading to 2.4.x.

     **TO KEEP YOUR 2.3.X DATA BY PRESERVING THE `PersistentVolumeClaim`** follow the *Preserving the PersistentVolumeClaim* procedure outlined in [Backing up and Exporting Data](../gettingStarted/backingupData.html). When following this procedure, you must install <span data-key-file="/home/jenkins/workspace/workspace/dita-converter/git_repo/conrefs.yml" data-conkeyref="conrefs/keyword.ta_short" data-variable="keyword.ta_short" class="md-conref">keyword.ta_short</span> 2.4.X into the same namespace as the 2.3.x version.
     
     If you have other customizations to your <span data-key-file="/home/jenkins/workspace/workspace/dita-converter/git_repo/conrefs.yml" data-conkeyref="conrefs/keyword.ta_short" data-variable="keyword.ta_short" class="md-conref">keyword.ta_short</span> instance (i.e. if you have edited other values in the custom resource YAML when installing 2.3.X), you may also wish to keep or re-apply them.
     You can view your current <span data-key-file="/home/jenkins/workspace/workspace/dita-converter/git_repo/conrefs.yml" data-conkeyref="conrefs/keyword.ta_short" data-variable="keyword.ta_short" class="md-conref">keyword.ta_short</span> instance configuration with the following command:
     
      ```bash {: codeblock}
      kubectl get transadvs.charts.ta.cloud.ibm.com ta -n <NAMESPACE> -o yaml
      ```
      

  3. In case you have modified the authentication.ocp.secretName value on install, run the script provided in Option 2.

  4. Install 2.4.X as per Installing document. If you have preserved the PersistentVolumeClaim, then you can use that as an existingClaim for your 2.4.X install.