Upgrading Watson Discovery to a newer 4.0 refresh

For a complete list of Watson Discovery refreshes available on Cloud Pak for Data Version 4.0, see Operator and operand versions.

Permissions you need for this task
You must be an administrator of the OpenShift® project (Kubernetes namespace) where Watson Discovery is installed.
When you need to complete this task
You must complete this task for each instance of Watson Discovery on your cluster. For example, if you have two instances of Watson Discovery on your cluster, you must complete this task twice.
Information you need to confirm before you start this task
Before you upgrade Watson Discovery, confirm the name of the project where Watson Discovery is installed.

Watson Discovery is installed in the same project as Cloud Pak for Data.

Information you need to complete this task
  • You cannot change the storage that is associated with this installation. If you try to change the storage, the upgrade will fail.

Before you begin

Ensure that the cluster meets the minimum requirements for Watson Discovery. For details, see System requirements.

Additionally, ensure that a cluster administrator completed the required Upgrade preparation tasks for your environment. Specifically, verify that a cluster administrator completed the following tasks:

  1. The latest Cloud Pak for Data refresh is installed. For details, see Upgrading Cloud Pak for Data.
  2. For environments that use a private container registry, such as air-gapped environments, the Watson Discovery software images are mirrored to the private container registry. For details, see Mirroring images to your container registry.
  3. The catalog source for Watson Discovery is updated. For details, see Updating catalog source.
  4. The operator for Watson Discovery is upgraded. For details, see Upgrading operator subscriptions.

If these tasks are not complete, the Watson Discovery upgrade will fail.

Attention: Unlike with previous 4.0.x releases, the 4.0.6 release requires down time while the upgrade is underway. Also, an upgrade to the 4.0.6 or later versions from an earlier 4.0.x release cannot be undone. You must back up the data to prevent any data loss that might occur if the upgrade is not completed successfully.
Starting with version 4.0.6, a new internal data structure is used by the service. When you upgrade from a previous 4.0.x version to 4.0.6 or later, the process migrates the internal data structure from the older version to the version that is introduced with the 4.0.6 release. Due to the complexity of the migration, you must back up your data before you upgrade. For more information about how to back up your data, see Backing up and restoring data.

The PostgreSQL component requires more disk space, typically 35% more, during the upgrade than was required for previous upgrades. The component needs to use extra resources to migrate the internal data structure. Use the mt-migration-size-estimator.sh script to estimate the disk usage that will be required for the upgrade so that you can prepare for it. The extra disk space is required for the duration of the upgrade process only, not for the daily operation of the service after it is upgraded. The tenant ID of the service instance does not change.

If you are upgrading from 4.0.0 or 4.0.2, there is one change to the installation process that you should know about. Prior to 4.0.3, you used the --action install-postgres-operator command to install a standalone EDB Cloud Native PostgreSQL operator as part of the Discovery service installation procedure. With 4.0.3 and later, you can use the PostgreSQL operator that is included with IBM Cloud Pak foundational services instead. If you are using a version of the foundational services that is earlier than version 3.13, see Upgrading IBM Cloud Pak® foundational services.

Prerequisite step

Before you can perform an in-place upgrade to versions 4.0.6, 4.0.7, or 4.0.8, you must complete this step. The Watson Discovery service assumes that the user who performs the upgrade has a user ID of admin. You must apply a patch that gives the appropriate user ID permission to perform the upgrade for your instance.

  1. From the Cloud Pak for Data web client, get the user ID of the owner of the instance that you want to upgrade.
  2. Download the wd-migration-uid-patch.zip patch from the Watson Developer Cloud GitHub repository.
  3. Extract the wd-migration-uid-patch.yaml file from the archive file, and then open it in a text editor.
  4. Replace the <user_id> variable with the user ID of the owner of the instance that you want to upgrade.
  5. Run the following command in a terminal that is logged in to the cluster:
    oc create -f wd-migration-uid-patch.yaml

Procedure

Complete the following tasks to upgrade Watson Discovery:

  1. Upgrading the service
  2. Verifying the upgrade
  3. Choosing a service upgrade plan
  4. What to do next

Upgrading the service

To upgrade Watson Discovery:

  1. Log in to Red Hat® OpenShift Container Platform as a user with sufficient permissions to complete the task:
    oc login OpenShift_URL:port
  2. Edit the WatsonDiscovery custom resource:
    oc edit WatsonDiscovery wd \
--namespace project-name
  3. Update the version entry to 4.0.9
  4. Save your changes and exit. For example, if you are using vi, hit esc and enter :wq.

When you update the custom resource, the Watson Discovery operator upgrades Watson Discovery.

Verifying the upgrade

The Watson Discovery operator continually monitors the contents of the custom resource and updates the microservices that comprise Watson Discovery as needed. The WatsonDiscovery microservice is defined by the wd custom resource. Watson Discovery is upgraded when the WatsonDiscovery status is Completed.

To check the status of the upgrade:

  1. Change to the project where Watson Discovery is installed: 
    oc project project-name
  2. Get the status of Watson Discovery (wd):
    oc get WatsonDiscovery wd -o jsonpath='{.status.watsonDiscoveryStatus} {"\n"}'

    Watson Discovery is ready when the command returns Completed.

Choosing a service upgrade plan

Use the Manual upgrade plan with Watson Discovery. Automatic upgrades and rollbacks are not fully supported currently.

What to do next

Upgrades from 4.0.0 or 4.0.2 releases only: Uninstall the version of the EDB Cloud Native PostgreSQL operator that you installed with the earlier release.

  1. Remove the subscription to the previously-installed operator and remove the cluster service version of the operator. For more information, see Updating the PostgreSQL operator subscription.
  2. Delete the EDB PostgreSQL license key:
    • If you're using ibm pak, enter this command:
      oc ibm-pak launch ibm-watson-discovery \
  --version 4.0.2
  --inventory discoveryOperators \
  --action delete-postgres-licensekey \
  --namespace project-name
    • If you're using cloudctl, enter this command:
      cloudctl case launch \
  --case ${OFFLINEDIR}/ibm-watson-discovery-4.0.2.tgz \
  --inventory discoveryOperators \
  --action delete-postgres-licensekey \
  --namespace project-name

The service is now ready to use.