Installing Watson Assistant

A project administrator can install the Watson Assistant service on IBM® Cloud Pak for Data.

Prerequisites

Required role: To complete this task, you must be an administrator of the project (namespace) where you will deploy Watson Assistant.

Before you install Watson Assistant, ensure that:

The Cloud Pak for Data control plane is already installed on your Red Hat® OpenShift® cluster. For details, see Installing IBM Cloud Pak for Data.
A cluster administrator has completed the steps in Setting up the cluster for Watson Assistant.
The cluster meets the minimum requirements for installing Watson Assistant. For details, see System requirements for services.
You completed the steps in Preparing to install and upgrade services.
You completed the steps in Creating an override file for Watson Assistant.
If you want to use a storage solution other than Portworx, take steps to configure it. For more information, see Using an alternate storage solution.
If you are installing on OpenShift 4.5 or higher, you must install the Events service. The service is required by the Analytics feature. Follow the instructions in Integrating with Cloud Platform Common Services to install the Events service. When you install the common services from the CLI, only complete the procedure named Installing the IBM Common Service Operator. The Analytics feature is not supported on OpenShift 3.11.

If you are installing multiple services on your cluster, you must run the installations one at a time and wait until the installation completes before installing another service. You cannot run the installations in parallel.

Tip: For a list of all available options, enter the following command:

./cpd-cli install --help

Procedure

Complete the appropriate steps to install Watson Assistant on your environment:
- Installing on clusters connected to the internet
- Installing on air-gapped clusters
Verifying that the installation completed successfully
Checking for available patches
Complete the tasks listed in What to do next

Installing on clusters connected to the internet

From your installation node:

Change to the directory where you placed the Cloud Pak for Data command-line interface and the repo.yaml file.
Log in to your Red Hat OpenShift cluster as a project administrator:
```
oc login OpenShift_URL:port
```

To install Watson Assistant, you must run the installer multiple times to install the following assemblies in this order:

edb-operator

Installs a EnterpriseDB PostgreSQL server that is used by the Watson Assistant service. Specify the following additional parameter with the installation command:

--optional-modules edb-pg-base:x86_64

For example:

cpd-cli install \
   --assembly edb-operator \
   --optional-modules edb-pg-base:x86_64 \
   --namespace zen \
   --repo repo.yaml \
   --cluster-pull-prefix $(oc registry info --internal)/zen \
   --transfer-image-to=$(oc registry info)/zen \
   --ask-push-registry-credentials \
   --insecure-skip-tls-verify

watson-assistant-operator

The assistant operator is a prerequisite for Watson Assistant that installs resources that are required by the service.

If you are installing on OpenShift 4.6, the following parameters are required, and you might need additional parameters depending on your environment:

cpd-cli install \
  --assembly watson-assistant-operator \
  --optional-modules watson-assistant-operand-ibm-events-operator:x86_64 \
  --override install-override.yaml \
  --namespace zen \
  --repo repo.yaml \
  --cluster-pull-prefix $(oc registry info --internal)/zen \
  --transfer-image-to=$(oc registry info)/zen \
  --ask-push-registry-credentials \
  --insecure-skip-tls-verify

Note:

If you are installing the service on OpenShift 3.11, do not include the optional-modules parameter. It is only required if the Analytics feature is enabled and the Analytics feature is not supported on OpenShift 3.11. For example:

cpd-cli install \
  --assembly watson-assistant-operator \
  --override install-override.yaml \
  --namespace zen \
  --repo repo.yaml \
  --cluster-pull-prefix $(oc registry info --internal)/zen \
  --transfer-image-to=$(oc get route/docker-registry -n default --template {{.spec.host}} )/zen \
  --ask-push-registry-credentials \
  --insecure-skip-tls-verify

watson-assistant

The assistant assembly installs the service. When you install this assembly, you must specify the --instance Instance_name parameter.

For example:

cpd-cli  install \
  --assembly watson-assistant \
  --instance wa001 \
  --override install-override.yaml \
  --namespace zen \
  --repo repo.yaml \
  --storageclass portworx-watson-assistant-sc \
  --cluster-pull-prefix $(oc registry info --internal)/zen \
  --transfer-image-to=$(oc registry info)/zen \
  --ask-push-registry-credentials \
  --insecure-skip-tls-verify

Run the following command to see a preview of what will be installed when you install each assembly.

Important: If you are using the internal Red Hat OpenShift registry and you are using the default self-signed certificate, specify the --insecure-skip-tls-verify flag to prevent x509 errors.

./cpd-cli install \
--repo ./repo.yaml \
--assembly Assembly_name \
--arch Cluster_architecture \  
--namespace Project \
--storageclass Storage_class_name \
--transfer-image-to Registry_location \
--cluster-pull-prefix Registry_from_cluster \
--ask-push-registry-credentials \
--dry-run

Important: By default, this command gets the latest version of the assembly. If you want to install a specific version of Watson Assistant, add the following line to your command after the --assembly flag:

--version Assembly_version \

The --latest-dependency flag gets the latest version of the dependent assemblies. If you remove the --latest-dependency flag, the installer will get the minimum version of the dependent assemblies.

Ensure that you use the same flags that your cluster administrator used when they completed Setting up the cluster for Watson Assistant. If your cluster administrator used the --version flag, ensure that you specify the same version of the assembly.

Add the following line to your installation command after the --namespace flag to specify the fully qualified name of your installation override file:

--override install-override.yaml

Replace the following values:

Variable	Replace with
`Assembly_version`	The version of Watson Assistant that you want to install. The assembly versions are listed in System requirements for services.
`Cluster_architecture`	Specify the architecture of your cluster hardware: For x86-64 hardware, remove this flag or specify `x86_64`
`Project`	Use the value provided by your cluster administrator. You should have obtained this information when you completed Preparing to install and upgrade services.
`Instance_name`	The name that you want to use for this instance of Watson Assistant. Specify a name that is as short as possible.
`Storage_class_name`	Use the value provided by your cluster administrator. You should have obtained this information when you completed Preparing to install and upgrade services. This value is typically `portworx-watson-assistant-sc`.
`Registry_location`	Use the value provided by your cluster administrator. You should have obtained this information when you completed Preparing to install and upgrade services. Specify a route to the registry followed by the namespace (project name). The route must be accessible from the machine where you run the install command. If the cluster you are installing does not have a route to the registry, you can to (temporarily) enable external access to the registries. For more information, see one of the following topics: OpenShift 4.6: Exposing the registry OpenShift 3.11:Securing and exposing the registry When you add the `--transfer-image-to` parameter, you can specify the registry location as follows: OpenShift 4.6: `oc get route/default-route -n openshift-image-registry \ --template='{{ .spec.host }}'` The command returns a route similar to `default-route-openshift-image-registry.apps.my_cluster_address`. Append the namespace to the route. For example: `default-route-openshift-image-registry.apps.my_cluster_address/zen` OpenShift 3.11: `oc get route/docker-registry -n default \ --template {{.spec.host}}` The command returns a route similar to `docker-registry-default.apps.my_cluster_address`. Append the namespace to the route. For example: `docker-registry-default.apps.my_cluster_address/zen`
`Registry_from_cluster`	Use the value provided by your cluster administrator. You should have obtained this information when you completed Preparing to install and upgrade services. Provide the username and user token as a password for a user with access to the registry when prompted. The username is the username from `oc login` command. The default username is typically `kubeadmin` for OpenShift 4.6 and `ocadmin` for OpenShift 3.11. You can get the user token to use as a password by specifying the following command: `$(oc whoami -t)` The password is populated for you.

Rerun the previous command without the --dry-run flag to install the first assembly.
Repeat the previous steps to install each assembly in order.

Installing on air-gapped clusters

From your installation node:

Change to the directory where you placed the Cloud Pak for Data command-line interface.
Log in to your Red Hat OpenShift cluster as a project administrator:
```
oc login OpenShift_URL:port
```
To install Watson Assistant, you must run the installer multiple times to install the following assemblies in this order:
Note: The examples show how to run the commands on Red Hat OpenShift 4.6 unless otherwise specified.
edb-operator
Installs a EnterpriseDB PostgreSQL server that is used by the Watson Assistant service. Specify the following additional parameter with the installation command:
```
--optional-modules edb-pg-base:x86_64
```
For example:
```
cpd-cli install \
--assembly edb-operator \
--optional-modules edb-pg-base:x86_64 \
--namespace zen \
--load-from cpd-cli-workspace \
--latest-dependency  \
--cluster-pull-prefix $(oc registry info --internal)/zen
```
watson-assistant-operator
The assistant operator is a prerequisite for Watson Assistant that installs resources that are required by the service.
If you are installing on OpenShift 4.6, the following parameters are required, and you might need additional parameters depending on your environment:
```
cpd-cli  install \
--assembly watson-assistant-operator \
--optional-modules watson-assistant-operand-ibm-events-operator:x86_64 \
--override install-override.yaml \
--namespace zen \
--load-from cpd-cli-workspace \
--latest-dependency \
--cluster-pull-prefix $(oc registry info --internal)/zen \
--storageclass portworx-watson-assistant-sc
```
Note:
If you are installing the service on OpenShift 3.11, do not include the optional-modules parameter. It is only required if the Analytics feature is enabled and the Analytics feature is not supported on OpenShift 3.11. For example:
./cpd-cli install \ --assembly watson-assistant-operator \ --override install-override.yaml \ --namespace zen \ --load-from cpd-cli-workspace \ --latest-dependency \ --cluster-pull-prefix $(oc registry info --internal)/zen \ --storageclass portworx-watson-assistant-sc
watson-assistant
The assistant assembly installs the service. When you install this assembly, you must specify the --instance Instance_name parameter.
For example:
```
./cpd-cli  install \
--assembly watson-assistant \
--storageclass portworx-watson-assistant-sc \
--instance wa001 \
--override install-override.yaml \
--namespace zen \
--load-from cpd-cli-workspace \
--latest-dependency \
--cluster-pull-prefix $(oc registry info --internal)/zen
```
If OpenShift is configured to use Open Virtual Networking with Kubernetes (OVN-Kubernetes) Container Network Interface (CNI) as the network provider instead of the default OpenShift Container Platform Software-defined Networking (SDN) network provider only: Disable a network policy setting to prevent the service pods from restarting unexpectedly after the installation.
1. Edit the watson-assistant-operator-ibm-watson-assistant-operator-prod-app-config configmap.
2. In the app_config.yaml file, look for the network_policy.enabled path, and change the value to false.

Run the following command to see a preview of what will be installed when you install each assembly.

Note:

Do not specify the --ask-pull-registry-credentials parameter.
Do not specify the --transfer-image-to parameter.

./cpd-cli install \
--assembly assembly_name \
--arch Cluster_architecture \
--namespace Project \
--storageclass Storage_class_name \
--load-from Image_directory_location \
--latest-dependency \
--cluster-pull-prefix Registry_from_cluster \
--dry-run

Note: If the assembly was downloaded using the delta-images command, remove the --latest-dependency flag from the command. If you don't remove the --latest-dependency flag you will get an error indicating that the flag cannot be used.

Ask your cluster administrator whether they specified the --latest-dependency flag when they completed Setting up the cluster for Watson Assistant. If they ran the adm command with the --latest-dependency flag, you must also run the install command with the flag.

Add the following line to your installation command after the --namespace flag to specify the fully qualified name of your installation override file:

--override install-override.yaml

Replace the following values:

Variable	Replace with
`Cluster_architecture`	Specify the architecture of your cluster hardware: For x86-64 hardware, remove this flag or specify `x86_64`
`Project`	Use the value provided by your cluster administrator. You should have obtained this information when you completed Preparing to install and upgrade services.
`Instance_name`	The name that you want to use for this instance of Watson Assistant. Specify a name that is as short as possible.
`Storage_class_name`	Use the value provided by your cluster administrator. You should have obtained this information when you completed Preparing to install and upgrade services. This value is typically `portworx-watson-assistant-sc`.
`Registry_from_cluster`	Use the value provided by your cluster administrator. You should have obtained this information when you completed Preparing to install and upgrade services.
`Image_directory_location`	The location of the cpd-cli-workspace directory.

Rerun the previous command without the --dry-run flag to install the first assembly.
Repeat the previous steps to install each assembly in order.

Verifying that the installation completed successfully

From your installation node:

Run the following command:
```
./cpd-cli status \
--assembly watson-assistant \
--namespace Project
```
If you specified an instance name when you installed Watson Assistant, add the following line to your command after the --assembly flag:
```
--instance Instance_name
```
Replace Instance_name with the value you used in when you installed Watson Assistant.
Replace Project with the value you used in when you installed Watson Assistant.
- If the installation completed successfully, the status of the assembly and the modules in the assembly is Ready.
- If the installation failed, contact IBM Support for assistance.

Checking for available patches

Determine whether there are any patches available for the version of Watson Assistant that you installed:

Clusters connected to the internet

Run the following command to check for patches:

./cpd-cli status \
--repo ./repo.yaml \
--namespace Project \ 
--assembly watson-assistant \
--patches \
--available-updates

If you specified an instance name when you installed Watson Assistant, add the following line to your command after the --assembly flag:

--instance Instance_name

Replace Instance_name with the value you used in when you installed Watson Assistant.

Air-gapped clusters

See the list of Available patches for Watson Assistant.

If you need to apply patches to the service, follow the guidance in Applying patches.

Note: For FIPS support, patch 1 for release 1.5.0 is required. The patch includes compatibility changes for FIPS.

What to do next

Administering Watson Assistant