Installing watsonx Assistant

An instance administrator can install watsonx Assistant on IBM Software Hub Version 5.2.

Who needs to complete this task?

Instance administrator To install watsonx Assistant, you must be an instance administrator. An instance administrator has permission to install 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 installation 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 installation 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 install multiple services at the same time, follow the process in Running a batch installation of solutions and services instead.
  • If you didn't install watsonx Assistant as part of a batch installation, complete this task to add watsonx Assistant to your environment.

    Repeat as needed If you are responsible for multiple instances of IBM Software Hub, you can repeat this task to install more instances of watsonx Assistant on the cluster.

Information you need to complete this task

Review the following information before you install watsonx Assistant:

Version requirements

All of the components that are associated with an instance of IBM Software Hub must be installed at the same release. For example, if the IBM Software Hub control plane is installed at Version 5.2.2, you must install watsonx Assistant at Version 5.2.2.

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
Security context constraint

watsonx Assistant works with the default Red Hat® OpenShift® Container Platform security context constraint, restricted-v2.

Common core services

watsonx Assistant requires the IBM Software Hub common core services.

If the common core services are not installed in the operands project for the instance, the common core services are automatically installed when you install watsonx Assistant. The common core services installation increases the amount of time the installation takes to complete.

Storage requirements
You must specify storage classes when you install watsonx Assistant. The following storage classes are recommended. However, if you don't use these storage classes on your cluster, ensure that you specify a storage class with an equivalent definition.
Storage Notes Storage classes
OpenShift Data Foundation When you install the service, specify file storage and block storage.
  • File storage: ocs-storagecluster-cephfs
  • Block storage: ocs-storagecluster-ceph-rbd
IBM Fusion Data Foundation When you install the service, specify file storage and block storage.
  • File storage: ocs-storagecluster-cephfs
  • Block storage: ocs-storagecluster-ceph-rbd
IBM Fusion Global Data Platform When you install the service, specify the same storage class for both file storage and block storage.
  • File storage:

    Either of the following storage classes:

    • ibm-spectrum-scale-sc
    • ibm-storage-fusion-cp-sc
  • Block storage:

    Either of the following storage classes:

    • ibm-spectrum-scale-sc
    • ibm-storage-fusion-cp-sc
IBM Storage Scale Container Native When you install the service, specify the same storage class for both file storage and block storage.
  • File storage: ibm-spectrum-scale-sc
  • Block storage: ibm-spectrum-scale-sc
Portworx When you install the service, the --storage_vendor=portworx option ensures that the service uses the correct storage classes.
  • File storage: portworx-shared-gp3
  • Block storage: portworx-watson-assistant-sc
NFS Not supported. Not applicable.
Amazon Elastic storage When you install the service, specify file storage and block storage.

File storage is provided by Amazon Elastic File System. Block storage is provided by Amazon Elastic Block Store.
  • File storage: efs-nfs-client
  • Block storage:

    Either of the following storage classes:

    • gp2-csi
    • gp3-csi
NetApp Trident When you install the service, specify the same storage class for both file storage and block storage.
  • File storage: ontap-nas
  • Block storage: ontap-nas
Nutanix Not supported. Not applicable.

Before you begin

This task assumes that the following prerequisites are met:

System requirements
This task assumes that the cluster meets the minimum requirements for watsonx Assistant.
Where to find more information
If this task is not complete, see System requirements.
Workstation
This task assumes that the workstation from which you will run the installation is set up as a client workstation and has the following command-line interfaces:
  • IBM Software Hub CLI: cpd-cli
  • OpenShift CLI: oc
Where to find more information
If this task is not complete, see Setting up a client workstation.
Control plane
This task assumes that the IBM Software Hub control plane is installed.
Where to find more information
If this task is not complete, see Installing an instance of IBM Software Hub.
Private container registry
If your environment uses a private container registry (for example, your cluster is air-gapped), this task assumes that the following tasks are complete:
  1. The watsonx Assistant software images are mirrored to the private container registry.
    Where to find more information
    If this task is not complete, see Mirroring images to a private container registry.
  2. The cpd-cli is configured to pull the olm-utils-v3 image from the private container registry.
    Where to find more information
    If this task is not complete, see Pulling the olm-utils-v3 image from the private container registry.
GPU operators
If you plan to use features that require GPUs, this task assumes that the operators required to use GPUs are installed.
Where to find more information
If this task is not complete, see Installing operators for services that require GPUs.
Red Hat OpenShift AI
If you plan to use features that require Red Hat OpenShift AI, this task assumes that Red Hat OpenShift AI is installed.
Where to find more information
If this task is not complete, see Installing Red Hat OpenShift AI.
Multicloud Object Gateway
This task assumes that the following tasks are complete:
  1. Multicloud Object Gateway is installed and configured.
    Where to find more information
    If this task is not complete, see Installing Multicloud Object Gateway.
  2. The secrets that enable watsonx Assistant to connect to Multicloud Object Gateway exist.
    Where to find more information
    If this task is not complete, see Creating secrets for services that use Multicloud Object Gateway.
Red Hat OpenShift Serverless Knative Eventing
This task assumes that Red Hat OpenShift Serverless Knative Eventing is installed.
Where to find more information
If this task is not complete, see Installing Red Hat OpenShift Serverless Knative Eventing.
Important:
  • watsonx Assistant supports only single-zone OpenShift deployments. It does not support multi-zone deployments.
  • You cannot install watsonx Assistant and watsonx™ Orchestrate on the same instance of IBM Software Hub. If you want to install these services on the same Red Hat OpenShift Container Platform cluster, you must install each service on a different instance of IBM Software Hub. For more information see Multitenancy considerations.

Procedure

Complete the following tasks to install watsonx Assistant:

  1. Specifying additional installation options
  2. Installing the service
  3. Validating the installation
  4. What to do next

Specifying installation options

If you plan to install watsonx Assistant, you can specify the following installation options in a file named install-options.yml in the cpd-cli work directory (For example: cpd-cli-workspace/olm-utils-workspace/work).

The parameters are optional. If you do not set these installation parameters, the default values are used. Uncomment the parameters that you want to override and update the values appropriately.

The sample YAML content uses the default values.

################################################################################
# watsonx Assistant parameters
################################################################################
#watson_assistant_size: Production
#watson_assistant_bigpv: false
#watson_assistant_analytics_enabled: true
#watson_assistant_watsonx_ai_type: embedded
#watson_assistant_syom_models: []
#watson_assistant_ootb_models: []
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 Fusion Data Foundation
  • IBM 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_watsonx_ai_type 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 GPU requirements for models.

Default value
The default value depends on whether you are installing or upgrading watsonx Assistant:
  • For installations, the default value is none.

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

  • For upgrades, the existing value is used as the default value.

    If you omit this option, the option, the current configuration is used.

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

The GPU features will not be enabled.
watson_assistant_syom_models Specify whether you want to use a specialized model that is specifically tuned for use with watsonx Assistant for:
Important: The following models will be automatically installed if you install Inference foundation models (watson_assistant_watsonx_ai_type: embedded) and you do not specify a value for watson_assistant_syom_models or watson_assistant_ootb_models:
  • ibm-granite-8b-unified-api-model-v2
  • granite-3-8b-instruct
Default value
[]
Valid values
[]
Do not install a specialized model.
ibm-granite-8b-unified-api-model-v2
Install the ibm-granite-8b-unified-api-model-v2 specialized model. This model enables assistants to:
  • Rewrite user questions to an understood format for conversational search
  • Gather information to fill in variables in a conversational skill
Including this parameter
Ensure that you uncomment the following line and specify the model name as a list item on a new line:
watson_assistant_syom_models:
  - ibm-granite-8b-unified-api-model-v2
watson_assistant_ootb_models Specify whether you want to use a general model for:
Important: The following models will be automatically installed if you install Inference foundation models (watson_assistant_watsonx_ai_type: embedded) and you do not specify a value for watson_assistant_syom_models or watson_assistant_ootb_models:
  • ibm-granite-8b-unified-api-model-v2
  • granite-3-8b-instruct
Default value
[]
Valid values
[]
Do not install a general model.
granite-3-8b-instruct
Install the granite-3-8b-instruct general model. This model enables assistants to:
  • Answer conversational search questions
Important: If you use a private container registry, you must explicitly mirror the granite-3-8b-instruct image to the private container registry.
llama-3-1-70b-instruct
Install the llama-3-1-70b-instruct general model. This model enables assistants to:
  • Rewrite user questions to an understood format for conversational search
  • Answer conversational search questions.
  • Gather information to fill in variables in a conversational skill
Important: If you use a private container registry, you must explicitly mirror the llama-3-1-70b-instruct image to the private container registry.
Including this parameter
Ensure that you uncomment the following line and specify the model name as a list item on a new line.
Install the granite-3-8b-instruct model
watson_assistant_ootb_models:
  - granite-3-8b-instruct
Install the llama-3-1-70b-instruct model
watson_assistant_ootb_models:
  - llama-3-1-70b-instruct
Install both models
watson_assistant_ootb_models:
  - granite-3-8b-instruct
  - llama-3-1-70b-instruct

Installing the service

To install watsonx Assistant:

  1. 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.
  2. Run the following command to create the required OLM objects for watsonx Assistant in the operators project for the instance:
    cpd-cli manage apply-olm \
--release=${VERSION} \
--cpd_operator_ns=${PROJECT_CPD_INST_OPERATORS} \
--components=watson_assistant
    Wait for the cpd-cli to return the following message before you proceed to the next step:
    [SUCCESS]... The apply-olm command ran successfully

    If the apply-olm fails, see Troubleshooting the apply-olm command during installation or upgrade.

  3. Create 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 appropriate command to create the custom resource.

    Default installation (without installation options)
    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} \
--license_acceptance=true
    Custom installation (with installation options)
    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
    IBM Fusion Data Foundation storage

    Run the appropriate command to create the custom resource.

    Default installation (without installation options)
    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} \
--license_acceptance=true
    Custom installation (with installation options)
    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
    IBM Fusion Global Data Platform storage
    Remember: When you use IBM Fusion Global Data Platform 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 appropriate command to create the custom resource.

    Default installation (without installation options)
    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} \
--license_acceptance=true
    Custom installation (with installation options)
    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
    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 appropriate command to create the custom resource.

    Default installation (without installation options)
    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} \
--license_acceptance=true
    Custom installation (with installation options)
    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
    Portworx storage

    Run the appropriate command to create the custom resource.

    Default installation (without installation options)
    cpd-cli manage apply-cr \
--components=watson_assistant \
--release=${VERSION} \
--cpd_instance_ns=${PROJECT_CPD_INST_OPERANDS} \
--storage_vendor=portworx \
--license_acceptance=true
    Custom installation (with installation options)
    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
    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 appropriate command to create the custom resource.

    Default installation (without installation options)
    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} \
--license_acceptance=true
    Custom installation (with installation options)
    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
    AWS with EFS and EBS storage

    Run the appropriate command to create the custom resource.

    Default installation (without installation options)
    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} \
--license_acceptance=true
    Custom installation (with installation options)
    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
    NetApp Trident
    Remember: When you use NetApp Trident storage, both ${STG_CLASS_BLOCK} and ${STG_CLASS_FILE} point to the same storage class, typically ontap-nas.

    Run the appropriate command to create the custom resource.

    Default installation (without installation options)
    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} \
--license_acceptance=true
    Custom installation (with installation options)
    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

Validating the installation

watsonx Assistant is installed 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

What to do next

Your next steps depend on the version of IBM Software Hub that you upgraded to:

Version 5.2.1 or later
  1. Complete Creating a service instance for watsonx Assistant from the web client.

After you complete the preceding steps, watsonx Assistant is ready to use.

Version 5.2.0