Upgrading watsonx Assistant from Version 4.7.x to Version 5.0

An instance administrator can upgrade watsonx Assistant from Cloud Pak for Data Version 4.7 to Version 5.0.

Who needs to complete this task?

Instance administrator To upgrade watsonx Assistant, you must be an instance administrator. An instance administrator has permission to manage software in the following projects:

The operators project for the instance

The operators for this instance of watsonx Assistant are installed in the operators project. In the upgrade commands, the ${PROJECT_CPD_INST_OPERATORS} environment variable refers to the operators project.

The operands project for the instance

The custom resources for the control plane and watsonx Assistant are installed in the operands project. In the upgrade commands, the ${PROJECT_CPD_INST_OPERANDS} environment variable refers to the operands project.

When do you need to complete this task?

Review the following options to determine whether you need to complete this task:

  • If you want to upgrade the control plane and one or more services at the same time, follow the process in Upgrading an instance of Cloud Pak for Data instead.
  • If you didn't upgrade watsonx Assistant when you upgraded the control plane, complete this task to upgrade watsonx Assistant.

    Repeat as needed If you are responsible for multiple instances of Cloud Pak for Data, you can repeat this task to upgrade more instances of watsonx Assistant on the cluster.

Information you need to complete this task

Review the following information before you upgrade watsonx Assistant:

Version requirements

All the components that are associated with an instance of Cloud Pak for Data must be installed at the same release. For example, if the Cloud Pak for Data control plane is at Version 5.0.3, you must upgrade watsonx Assistant to Version 5.0.3.

Environment variables
The commands in this task use environment variables so that you can run the commands exactly as written.
  • If you don't have the script that defines the environment variables, see Setting up installation environment variables.
  • To use the environment variables from the script, you must source the environment variables before you run the commands in this task. For example, run:
    source ./cpd_vars.sh
Common core services
watsonx Assistant requires the Cloud Pak for Data common core services.

If the common core services are not at the correct version in the operands project for the instance, the common core services are automatically upgraded when you upgrade watsonx Assistant. The common core services upgrade increases the amount of time the upgrade takes to complete.

Storage requirements
Specify the storage that you use in your existing installation. You cannot change the storage that is associated with watsonx Assistant during an upgrade. Ensure that the environment variables point to the correct storage classes for your environment.

Before you begin

This task assumes that the following prerequisites are met:

Prerequisite Where to find more information
The cluster meets the minimum requirements for watsonx Assistant. If this task is not complete, see System requirements.
The workstation from which you will run the upgrade is set up as a client workstation and has the following command-line interfaces:
  • Cloud Pak for Data CLI: cpd-cli
  • OpenShift® CLI: oc
 If this task is not complete, see Updating client workstations.
The Cloud Pak for Data control plane is upgraded. If this task is not complete, see Upgrading an instance of Cloud Pak for Data.
For environments that use a private container registry, such as air-gapped environments, the watsonx Assistant software images are mirrored to the private container registry. If this task is not complete, see Mirroring images to a private container registry.
For environments that use a private container registry, such as air-gapped environments, the cpd-cli is configured to pull the olm-utils-v3 image from the private container registry. If this task is not complete, see Pulling the olm-utils-v3 image from the private container registry.
Multicloud Object Gateway is upgraded, if needed. If this task is not complete, see Installing Multicloud Object Gateway.
Red Hat® OpenShift Serverless Knative Eventing is installed and configured. If this task is not complete, see Installing Red Hat OpenShift Serverless Knative Eventing.

Procedure

Complete the following tasks to upgrade watsonx Assistant:

  1. Back up your data.

    For more information, see Backing up your data in Cloud Pak for Data in the watsonx Assistant product documentation.

  2. Logging in to the cluster
  3. Backing up and retaining temporary patches
  4. Specifying additional installation options
  5. Upgrading the service
  6. Validating the upgrade
  7. Cleaning up resources
  8. What to do next

Specifying installation options

When you upgrade watsonx Assistant, specify the following option in the install-options.yml file in the work directory.

################################################################################
# watsonx Assistant parameters
################################################################################
#watson_assistant_size: Production
#watson_assistant_bigpv: false
#watson_assistant_analytics_enabled: true
#watson_assistant_GPU_features_enabled: false
#watson_assistant_watsonx_ai_type: embedded
Property Description
watson_assistant_size The deployment size for watsonx Assistant.

The deployment size determines the number of resources allocated to watsonx Assistant.

Default value
Production
Valid values
large
A large deployment has at least 3 replicas of each pod to support production-scale workloads with a large number of concurrent API calls. large is equivalent to the large scaleConfig setting.
Production
A production deployment has at least two replicas of each pod to support production-scale workloads. Production is equivalent to the medium scaleConfig setting.
Starter
A starter deployment has fewer resources and less computing power than a production deployment. Starter is the equivalent to the small scaleConfig setting.

In previous releases, this deployment type was called the development deployment type.
watson_assistant_bigpv Specify whether to create larger physical volumes to improve IOPS performance.

Create larger physical volumes if your storage class IOPS performance depends on the size of the physical volume.

Important: You cannot change this setting after you install watsonx Assistant.

You do not need to create larger physical volumes if you use the following storage:

  • Red Hat OpenShift Data Foundation
  • IBM Storage Fusion Data Foundation
  • IBM Storage Fusion Global Data Platform
  • IBM Storage Scale Container Native
  • Portworx
  • IBM Cloud Block Storage
Default value
false
Valid values
false
Create physical volumes with the default size.
true
Create larger physical volumes to improve IOPS performance.
watson_assistant_analytics_enabled Specify whether to store chat logs and analytics.
Default value
true
Valid values
false
Do not store chat logs and analytics.
true
Store chat logs and analytics.
watson_assistant_GPU_features_enabled

5.0.0 5.0.1 5.0.2 This parameter applies to Versions 5.0.0, 5.0.1, and 5.0.2 only.

If you are on Version 5.0.3 or later, see the entry for watson_assistant_watsonx_ai_type.

Specify whether to enable the following features, which require GPUs:

For more information about supported GPUs, see the Hardware requirements for watsonx Assistant.

Default value
false
Valid values
false
Do not enable features that require GPUs.
true
Enable features that require GPUs.
watson_assistant_watsonx_ai_type

5.0.3 or later This parameter applies to Versions 5.0.3 and later.

If you are on Version 5.0.0, 5.0.1, or 5.0.2, see the entry for watson_assistant_GPU_features_enabled.

Specify this option if you want to install Inference foundation models (watsonx_ai_ifm) to enable the following features, which require GPUs:

Omit this option if you do not want to enable the preceding features.

For more information about supported GPUs, see the Hardware requirements for watsonx Assistant.

Default value
No default.

If you omit this option, the GPU features are not enabled.

Valid values
embedded
Install Inference foundation models (watsonx_ai_ifm) to enable features that require GPUs.

Logging in to the cluster

  • Log the cpd-cli in to the Red Hat OpenShift Container Platform cluster:
    ${CPDM_OC_LOGIN}
    Remember: CPDM_OC_LOGIN is an alias for the cpd-cli manage login-to-ocp command.

Backing up and retaining temporary patches

Upgrading watsonx Assistant removes all pre-existing temporary patches that do not have the label 'type=critical-configuration'. If you need to retain some temporary patches, you can preserve them before upgrading by labeling them as critical. For example, you might have a custom configuration that is specific to your environment and was not included in the new release.
Note:
  • Ignore this section if you don't find any pre-existing temporary patches.
  • If you are unsure about what patches need to be retained, contact IBM Support.

To back up and label the patches that need to be retained, follow these steps:

  1. Run the following command to list all temporary patches for your instances. Save the list to the file patches_list.txt.

    oc get temporarypatch -n ${PROJECT_CPD_INST_OPERANDS}   >patches_list.txt

  2. Save the YAML file for your existing temporary patches by running the following command:

    oc get temporarypatch -o yaml > old_patch_backups.yaml
  3. Get the list of the temporary patches from your deployment to determine which patches you want to preserve.
    oc get temporarypatch -n ${PROJECT_CPD_INST_OPERANDS}
  4. Apply or remove the "type": "critical-configuration" label as appropriate:
    • For all patches that you want to retain, use the following command:
      oc label temporarypatch <patch_name> type=critical-configuration

      For example:

      oc label temporarypatch wa-store-assistant-limits type=critical-configuration
    • For the patches that you want to remove, use the following command:
      oc label temporarypatch <patch_name> type-

      For example:

      oc label temporarypatch wa-store-assistant-limits type-

  5. Run the following commands to verify that the temporary patches you want to preserve have the label type=critical-configuration:

    oc get temporarypatch -n ${PROJECT_CPD_INST_OPERANDS} -l type=critical-configuration
    oc get temporarypatch -n ${PROJECT_CPD_INST_OPERANDS} --show-labels

Upgrading the service

Important: The Operator Lifecycle Manager (OLM) objects for watsonx Assistant were updated when you upgraded the Cloud Pak for Data. The cpd-cli manage apply-olm updates all of the OLM objects in the operators project at the same time.
  • Update the custom resource for watsonx Assistant.

    The command that you run depends on the storage on your cluster:

    Red Hat OpenShift Data Foundation storage

    Run the following command to create the custom resource.

    cpd-cli manage apply-cr \
--components=watson_assistant \
--release=${VERSION} \
--cpd_instance_ns=${PROJECT_CPD_INST_OPERANDS} \
--block_storage_class=${STG_CLASS_BLOCK} \
--file_storage_class=${STG_CLASS_FILE} \
--param-file=/tmp/work/install-options.yml \
--license_acceptance=true \
--upgrade=true
    IBM Storage Fusion Data Foundation storage

    Run the following command to create the custom resource.

    cpd-cli manage apply-cr \
--components=watson_assistant \
--release=${VERSION} \
--cpd_instance_ns=${PROJECT_CPD_INST_OPERANDS} \
--block_storage_class=${STG_CLASS_BLOCK} \
--file_storage_class=${STG_CLASS_FILE} \
--param-file=/tmp/work/install-options.yml \
--license_acceptance=true \
--upgrade=true
    IBM Storage Fusion Global Data Platform storage
    Remember: When you use IBM Storage Fusion storage, both ${STG_CLASS_BLOCK} and ${STG_CLASS_FILE} point to the same storage class, typically ibm-spectrum-scale-sc or ibm-storage-fusion-cp-sc.

    Run the following command to create the custom resource.

    cpd-cli manage apply-cr \
--components=watson_assistant \
--release=${VERSION} \
--cpd_instance_ns=${PROJECT_CPD_INST_OPERANDS} \
--block_storage_class=${STG_CLASS_BLOCK} \
--file_storage_class=${STG_CLASS_FILE} \
--param-file=/tmp/work/install-options.yml \
--license_acceptance=true \
--upgrade=true
    IBM Storage Scale Container Native storage
    Remember: When you use IBM Storage Scale Container Native storage, both ${STG_CLASS_BLOCK} and ${STG_CLASS_FILE} point to the same storage class, typically ibm-spectrum-scale-sc.

    Run the following command to create the custom resource.

    cpd-cli manage apply-cr \
--components=watson_assistant \
--release=${VERSION} \
--cpd_instance_ns=${PROJECT_CPD_INST_OPERANDS} \
--block_storage_class=${STG_CLASS_BLOCK} \
--file_storage_class=${STG_CLASS_FILE} \
--param-file=/tmp/work/install-options.yml \
--license_acceptance=true \
--upgrade=true
    Portworx storage

    Run the following command to create the custom resource.

    cpd-cli manage apply-cr \
--components=watson_assistant \
--release=${VERSION} \
--cpd_instance_ns=${PROJECT_CPD_INST_OPERANDS} \
--storage_vendor=portworx \
--param-file=/tmp/work/install-options.yml \
--license_acceptance=true \
--upgrade=true
    AWS with EFS storage only
    Remember: When you use EFS storage, both ${STG_CLASS_BLOCK} and ${STG_CLASS_FILE} point to the same storage class, typically efs-nfs-client.

    Run the following command to create the custom resource.

    cpd-cli manage apply-cr \
--components=watson_assistant \
--release=${VERSION} \
--cpd_instance_ns=${PROJECT_CPD_INST_OPERANDS} \
--block_storage_class=${STG_CLASS_BLOCK} \
--file_storage_class=${STG_CLASS_FILE} \
--param-file=/tmp/work/install-options.yml \
--license_acceptance=true \
--upgrade=true
    AWS with EFS and EBS storage

    Run the following command to create the custom resource.

    cpd-cli manage apply-cr \
--components=watson_assistant \
--release=${VERSION} \
--cpd_instance_ns=${PROJECT_CPD_INST_OPERANDS} \
--block_storage_class=${STG_CLASS_BLOCK} \
--file_storage_class=${STG_CLASS_FILE} \
--param-file=/tmp/work/install-options.yml \
--license_acceptance=true \
--upgrade=true
    NetApp Trident
    Remember: When you use NetApp Trident storage, both ${STG_CLASS_BLOCK} and ${STG_CLASS_FILE} point to the same storage class.

    Run the following command to create the custom resource.

    cpd-cli manage apply-cr \
--components=watson_assistant \
--release=${VERSION} \
--cpd_instance_ns=${PROJECT_CPD_INST_OPERANDS} \
--block_storage_class=${STG_CLASS_BLOCK} \
--file_storage_class=${STG_CLASS_FILE} \
--param-file=/tmp/work/install-options.yml \
--license_acceptance=true \
--upgrade=true

Validating the upgrade

watsonx Assistant is upgraded when the apply-cr command returns:
[SUCCESS]... The apply-cr command ran successfully

If you want to confirm that the custom resource status is Completed, you can run the cpd-cli manage get-cr-status command:

cpd-cli manage get-cr-status \
--cpd_instance_ns=${PROJECT_CPD_INST_OPERANDS} \
--components=watson_assistant

Cleaning up resources

Who needs to complete this task?
You must be an administrator of the project where watsonx Assistant is installed.
When do you need to complete this task?
Complete this task to clean up resources after you upgrade watsonx Assistant.

To delete remaining resources:

  1. Delete the Store Cronjob as a cleanup process:
    oc delete cronjob ${INSTANCE}-store-cronjob
  2. Verify that the job deleted successfully:
    oc get cronjob -n ${PROJECT_CPD_INST_OPERANDS}
    After a few minutes, a new job with the same name should reappear.

Upgrading existing service instances

The service instances are automatically upgraded when you upgrade watsonx Assistant.

What to do next

watsonx Assistant is ready to use. For information about getting started, see Building an assistant with watsonx Assistant. To enable Red Hat OpenShift Horizontal Pod Autoscaler (HPA) for watsonx Assistant to automatically increase or decrease pods in response to CPU or memory consumption, see Automatically scaling resources for services.