IBM Content Assistant Client Managed Software

https://www.ibm.com/docs/en/cacms/1.0.x
Admin
IBM Content Assistant Client Managed Software is an enterprise solution for managing and deploying...
Tokens:68,298
Snippets:472
Trust Score:10
Update:10 months ago
Show doc for...
Tokens:
Raw
### Install IBM Content Assistant CLI using pip

Source: https://www.ibm.com/docs/en/cacms/1.0.x/index_topic=line-installing-content-assistant-cli-tool

This command installs the IBM Content Assistant CLI tool from a local Python wheel file. Ensure you have pip installed and the wheel file is accessible in your current directory.

```bash
pip install ibmca-1.0.0-py3-none-any.whl
```

--------------------------------

### Example oc mirror Command for Catalog Mirroring

Source: https://www.ibm.com/docs/en/cacms/1.0.x/index_topic=mirror-mirroring-catalogs-private-registry-bastion-server

This is an example command generated by `oc ibm-pak generate mirror-manifests` used to mirror the curated catalog to the target registry. It utilizes the `oc mirror` command with a configuration file and specifies the target registry. Note that arguments might vary based on the `oc-mirror` plug-in version.

```bash
oc mirror --config $IBMPAK_HOME/.ibm-pak/data/publish/latest/image-set-config.yaml docker://$TARGET_REGISTRY --dest-skip-tls --max-per-registry=6
```

--------------------------------

### Verify IBM Content Assistant CLI Installation

Source: https://www.ibm.com/docs/en/cacms/1.0.x/index_topic=line-installing-content-assistant-cli-tool

This command checks if the IBM Content Assistant CLI tool has been successfully installed by displaying its version. This is a crucial step to confirm the installation's integrity.

```bash
ibmca --version
```

--------------------------------

### Content Assistant Configuration Parameters - YAML Example

Source: https://www.ibm.com/docs/en/cacms/1.0.x/index_topic=reference-content-assistant-parameters

An example of a YAML configuration for Content Assistant, demonstrating the structure and key parameters. This includes settings for API secrets, architecture, custom annotations, labels, replicas, and rolling updates.

```yaml
content_assistant_secret_name: ibm-content-assistant-secret
arch:
  amd64: 3
node_affinity:
  custom_node_selector_match_expression:
    - key: kubernetes.io/hostname
      operator: In
      values:
        - worker0
        - worker1
        - worker3
custom_annotations:
  customAnnotationKey: customAnnotationValue
custom_labels:
  customLabelKey: customLabelValue
replicas: 2
rolling_update:
  max_unavailable: 99%
  max_surge: 1
```

--------------------------------

### Clone ibm-content-assistant-client-managed-software Repository

Source: https://www.ibm.com/docs/en/cacms/1.0.x/index_topic=cluster-downloading-content-assistant-client-managed-software-repository

This command clones the ibm-content-assistant-client-managed-software repository from GitHub to your local machine. This repository contains necessary files for deploying the FNCM GenAI Connector Service. Ensure you have Git installed and configured.

```bash
git clone https://github.com/IBM/ibm-content-assistant-client-managed-software.git
```

--------------------------------

### Navigate to Script Directory (Bash)

Source: https://www.ibm.com/docs/en/cacms/1.0.x/index_topic=operator-installing-by-running-script

Changes the current directory to the location of the IBM Content Assistant client-managed-software scripts. This is a prerequisite for running subsequent installation commands.

```bash
cd ./ibm-content-assistant-client-managed-software/scripts
```

--------------------------------

### Example imageDetails.toml Structure

Source: https://www.ibm.com/docs/en/cacms/1.0.x/index_topic=cncf-getting-access-images-from-local-image-registry

Illustrates the expected format and content of the imageDetails.toml file, which specifies the repository and tag information for FNCM GenAI Connector Service components.

```toml
# ########################################################
# ## IBM Content Assistant Component Image Details ##
```

--------------------------------

### Run load_images.py in Push Mode (Interactive)

Source: https://www.ibm.com/docs/en/cacms/1.0.x/index_topic=pycagodo-downloading-case-packages-mirroring-images-in-airgap-environment

Execute the load_images.py script to push container images to the private registry. This interactive mode guides the user through confirming mirror generation and selecting channels.

```bash
python3 load_images.py --airgap push
```

--------------------------------

### Configure Podman Registry Authentication

Source: https://www.ibm.com/docs/en/cacms/1.0.x/index_topic=mirror-mirroring-catalogs-private-registry-bastion-server

If Podman is installed on the bastion host, this command sets the `REGISTRY_AUTH_FILE` environment variable to point to the Podman authentication file. This ensures `podman login` can access and update the registry credentials.

```bash
export REGISTRY_AUTH_FILE=$XDG_RUNTIME_DIR/containers/auth.json
```

--------------------------------

### Configure IBM Cloud-Pak OCI Registry Repository

Source: https://www.ibm.com/docs/en/cacms/1.0.x/index_topic=environment-optional-downloading-case-package-manually

This command configures the 'IBM Cloud®-Pak OCI registry' as the default repository for downloading CASE files from the oci:cp.icr.io/cpopen registry. It is a prerequisite before running the 'oc ibm-pak get' command.

```bash
oc ibm-pak config repo 'IBM Cloud-Pak OCI registry' -r oci:cp.icr.io/cpopen --enable
```

--------------------------------

### CatalogSource Resource Definition for IBM Content Assistant Operator

Source: https://www.ibm.com/docs/en/cacms/1.0.x/index_topic=operator-installing-using-openshift-console

This YAML defines a CatalogSource resource that adds the IBM Content Assistant Catalog to the OperatorHub. It specifies the display name, publisher, source type, and the image registry for the catalog. Replace `<namespace>` with your target namespace and `<digest-xxxx>` with the actual digest obtained from the catalogsource.yaml file. This is a prerequisite for installing the operator.

```yaml
apiVersion: operators.coreos.com/v1alpha1
kind: CatalogSource
metadata:
  name: ibm-content-assistant-operator-catalog
  namespace: <namespace>
spec:
  displayName: ibm-content-assistant-operator
  publisher: IBM
  sourceType: grpc
  image: icr.io/cpopen/ibm-content-assistant-catalog@sha256:<digest-xxxx>
```

--------------------------------

### Deploy IBM Content Assistant Operator (Python - Interactive)

Source: https://www.ibm.com/docs/en/cacms/1.0.x/index_topic=operator-installing-by-running-script

Runs the operator deployment script in interactive mode. This prompts the user for configuration details such as license acceptance, platform type, image registry, namespace, and global catalog namespace settings.

```python
python3 deploy_operator.py
```

--------------------------------

### Python Script for Image Mirroring: load_images.py CLI Help

Source: https://www.ibm.com/docs/en/cacms/1.0.x/index_topic=pycagodo-downloading-case-packages-mirroring-images-in-airgap-environment

Displays the command-line interface help for the load_images.py script, outlining available options, customization flags, and commands for generating image details and pushing images.

```bash
python3 load_images.py --help

Usage: load_images.py [OPTIONS] COMMAND [ARGS]...

IBM Content Assistant Load Images CLI.

Options:
  --version                      Show version and exit. 
  --install-completion           Install completion for the current shell.
  --show-completion              Show completion for the current shell, to copy it or customize the installation.
  --help                         Show this message and exit.

Customization and Utils:
  --silent     --no-silent       Enable Silent Install (no prompts). [default: no-silent]
  --verbose    --no-verbose      Enable verbose logging. [default: no-verbose]
  --airgap     --no-airgap       Enable OCP Airgap mode, [default: no-airgap]
  --dryrun     --no-dryrun       Perform a dry run [default: no-dryrun]

Commands:  
  generate       Generate the image details file.
  push           Push images to a registry based on existing image details file.

```

--------------------------------

### Install Python Dependencies

Source: https://www.ibm.com/docs/en/cacms/1.0.x/index_topic=cncf-getting-access-images-from-local-image-registry

Installs the necessary Python packages listed in the requirements.txt file using pip. This ensures that the load_images.py script has all its required libraries to function correctly.

```bash
python3 -m pip install -r requirements.txt
```

--------------------------------

### Run Prerequisite Script - Validate Mode

Source: https://www.ibm.com/docs/en/cacms/1.0.x/index_topic=service-generating-simple-custom-resource-deployment-files

Executes the prerequisite script with the 'validate' command to check the configuration and the environment for a successful deployment. This includes verifying storage class existence, PVC creation capabilities, and vector database connectivity.

```python
python3 prerequisites.py validate
```

--------------------------------

### Install Podman CLI using yum

Source: https://www.ibm.com/docs/en/cacms/1.0.x/index_topic=cluster-preparing-client-connect-kubernetes

Installs the Podman CLI using the yum package manager. This is necessary for OpenShift-based platforms when downloading container images to a private registry, as OpenShift does not support Docker login.

```bash
yum -y install podman
```

--------------------------------

### Install and Check kubectl Version

Source: https://www.ibm.com/docs/en/cacms/1.0.x/index_topic=cluster-preparing-client-connect-kubernetes

Installs the latest stable version of the Kubernetes kubectl CLI and checks the client version. It ensures compatibility with the cluster, recommending a version within one minor version of the cluster.

```bash
export KUBECTL_VERSION=$(curl -s https://storage.googleapis.com/kubernetes-release/release/stable.txt)
curl -LO "https://storage.googleapis.com/kubernetes-release/release/${KUBECTL_VERSION}/bin/linux/amd64/kubectl"
kubectl version --client
```

--------------------------------

### Display Help for clean_deployment.py Script

Source: https://www.ibm.com/docs/en/cacms/1.0.x/index_topic=components-uninstalling-by-running-script

This command displays the help message for the clean_deployment.py script, outlining its usage, options, and available commands. It's useful for understanding the script's capabilities and how to interact with it.

```bash
python3 clean_deployment.py --help
```

--------------------------------

### Repository Structure of ibm-content-assistant-client-managed-software

Source: https://www.ibm.com/docs/en/cacms/1.0.x/index_topic=cluster-downloading-content-assistant-client-managed-software-repository

The ibm-content-assistant-client-managed-software repository follows a specific directory structure, including directories for descriptors and scripts, a README file, and a version configuration file. This structure helps in organizing the deployment artifacts.

```tree
ibm-content-assistant-client-managed-software/
├── descriptors/
├── scripts/
├── README.md
└── version.toml
```

--------------------------------

### Display Help for load_images.py Script

Source: https://www.ibm.com/docs/en/cacms/1.0.x/index_topic=cncf-getting-access-images-from-local-image-registry

Displays the usage information and available options/commands for the load_images.py script. This is useful for understanding the script's capabilities and how to run it.

```bash
python3 load_images.py --help
```

--------------------------------

### Get Operator Role using oc get role

Source: https://www.ibm.com/docs/en/cacms/1.0.x/index_topic=operator-installing-using-openshift-console

This command retrieves the role associated with the 'ibm-content-assistant-operator' deployment. It filters the output to find the specific role name, which might be used for access control. The command relies on the 'oc' CLI tool and assumes the operator is deployed in the current Kubernetes context.

```bash
oc get role | grep ibm-content-assistant-operator | sort -t"t" -k1r | awk 'NR==1{print $1}'
```

--------------------------------

### Generate Mirror Manifests for CASE

Source: https://www.ibm.com/docs/en/cacms/1.0.x/index_topic=mirror-mirroring-catalogs-private-registry-bastion-server

Generates the necessary mirror manifests for a given CASE and target registry. The command outputs instructions for the actual mirroring process using `oc mirror`. The manifests are stored in `~/.ibm-pak/data/mirror/<CASE_NAME>/<CASE_VERSION>`.

```bash
oc ibm-pak generate mirror-manifests $CASE_NAME $TARGET_REGISTRY \
  --version $CASE_VERSION
```

--------------------------------

### Get IBM Operator CSV Name

Source: https://www.ibm.com/docs/en/cacms/1.0.x/index_topic=support-troubleshooting-container

Retrieves the Cluster Service Version (CSV) name for the 'ibm-cas-operator' using `oc get csv` and `grep`. This name is often required for subsequent `oc patch` operations. It outputs the CSV name to standard output.

```shell
CSV=$(oc get csv |grep ibm-cas-operator | awk '{print $1}') 
echo $CSV
```

--------------------------------

### Run Prerequisite Script - Gather Mode (Silent)

Source: https://www.ibm.com/docs/en/cacms/1.0.x/index_topic=service-generating-simple-custom-resource-deployment-files

Executes the prerequisite script with the 'gather' command and the '--silent' flag to gather information non-interactively. All required parameters should be pre-configured in the silent_install_prerequisites.toml file.

```python
python3 prerequisites.py gather --silent
```

--------------------------------

### Navigate to Scripts Directory

Source: https://www.ibm.com/docs/en/cacms/1.0.x/index_topic=cncf-getting-access-images-from-local-image-registry

Changes the current directory to the 'scripts' folder within the downloaded repository. This is a prerequisite step before running the load_images.py script or installing its dependencies.

```bash
cd ./scripts
```

--------------------------------

### List Available CASE Files for Download

Source: https://www.ibm.com/docs/en/cacms/1.0.x/index_topic=environment-optional-downloading-case-package-manually

This command lists all available CASE files that can be downloaded using the ibm-pak CLI. It helps users identify the specific CASE files relevant to their needs. Use '--help' for more detailed options.

```bash
oc ibm-pak list
```

```bash
oc ibm-pak list --help
```

--------------------------------

### Monitor Operator Pod Status (OCP)

Source: https://www.ibm.com/docs/en/cacms/1.0.x/index_topic=operator-installing-manually

Monitors the status of the operator pod in real-time using the `oc get pods -w` command. This helps verify that the operator has been successfully deployed and is running.

```shell
oc get pods -w
```

--------------------------------

### Run Prerequisite Script - Gather Mode (Interactive)

Source: https://www.ibm.com/docs/en/cacms/1.0.x/index_topic=service-generating-simple-custom-resource-deployment-files

Executes the prerequisite script with the 'gather' command to collect necessary information for a new deployment. The script will prompt the user for input.

```python
python3 prerequisites.py gather
```

--------------------------------

### Configure Docker Registry Authentication (Linux)

Source: https://www.ibm.com/docs/en/cacms/1.0.x/index_topic=mirror-mirroring-catalogs-private-registry-bastion-server

For Docker installations on Linux, this command sets the `REGISTRY_AUTH_FILE` environment variable to the Docker configuration file. This is necessary for `docker login` to store and retrieve registry credentials.

```bash
export REGISTRY_AUTH_FILE=$HOME/.docker/config.json
```

--------------------------------

### Monitor Operator Logs with oc logs

Source: https://www.ibm.com/docs/en/cacms/1.0.x/index_topic=operator-installing-using-openshift-console

This command streams the logs of the 'ibm-content-assistant-operator' deployment in real-time. It is useful for observing the operator's behavior and troubleshooting deployment issues. No specific input is required, and the output is the live log stream from the operator pod.

```bash
oc logs -f deployment/ibm-content-assistant-operator
```

--------------------------------

### Configure Probe Behavior

Source: https://www.ibm.com/docs/en/cacms/1.0.x/index_topic=reference-content-assistant-parameters

Defines the behavior of startup, liveness, and liveness probes. These probes help Kubernetes determine the health of the container and restart it if necessary. Parameters include initial delay, period, timeout, and failure thresholds.

```yaml
probe:
  startup:
    initial_delay_seconds: 120
    period_seconds: 30
    timeout_seconds: 10
    failure_threshold: 40
  liveness:
    period_seconds: 30
    timeout_seconds: 5
    failure_threshold: 6
```

--------------------------------

### Monitor Operator Pod Status (Kubectl)

Source: https://www.ibm.com/docs/en/cacms/1.0.x/index_topic=operator-installing-by-running-script

Monitors the status of pods in the Kubernetes cluster, specifically waiting for the operator pod to reach the 'Running' state. The '-w' flag enables watch mode.

```bash
kubectl get pods -w
```

--------------------------------

### Get Pods with Verbose Output (Kubectl)

Source: https://www.ibm.com/docs/en/cacms/1.0.x/index_topic=support-troubleshooting-container

This command lists all pods in the current namespace with increased verbosity. The `-v` flag provides more detailed output, which can be useful for troubleshooting.

```bash
kubectl -v get pods
```

--------------------------------

### Java: Content Engine GenAI Base Query Sample

Source: https://www.ibm.com/docs/en/cacms/1.0.x/index_topic=applications-content-engine-java-api-samples

This Java sample demonstrates how to connect to a Content Engine instance, create a GenaiBaseQuery object, set the prompt and model name, save the query, and retrieve the response from the generative AI model. It requires the Content Engine Java API and appropriate connection details.

```java
import javax.security.auth.Subject;

import com.filenet.api.constants.RefreshMode;
import com.filenet.api.core.CmAbstractPersistable;
import com.filenet.api.core.Connection;
import com.filenet.api.core.Domain;
import com.filenet.api.core.Factory;
import com.filenet.api.core.ObjectStore;
import com.filenet.api.util.UserContext;


public class BaseQuerySample {

	
	
	public static void main(String[] args) {
	    
	String url = “<CE URL>”; //eg. "http://localhost:9080/wsi/FNCEWS40MTOM/";
	String objectStoreName = “<your object store name>”; 
	String username = "<login user>"
String password = "<password>"
	    
	    // connecting to the CE isntance
        Connection connection = Factory.Connection.getConnection(url);
        Subject sub = UserContext.createSubject(connection, username, password, 
"FileNetP8WSI");
        UserContext uc = UserContext.get();     
        uc.pushSubject(sub);

        //fetchless instantiation of CE domain and object store 
        Domain domain = Factory.Domain.getInstance(connection, null);
        ObjectStore os = Factory.ObjectStore.getInstance(domain, objectStoreName); 
        
        //your question to generative AI model, here is an example
        String queryStr = "what is ECM? " ;
        
        //create a query object with an optional LLM model name. 
        CmAbstractPersistable baseQuery = 
	Factory.CmAbstractPersistable.createInstance(os, "GenaiBaseQuery");
        baseQuery.getProperties().putObjectValue("GenaiLLMPrompt", queryStr);
        baseQuery.getProperties().putObjectValue("GenaiLLMModelName", "google/flan-ul2");
    	
        // create a query object, and change preprocessor will handle query execution in CE server and save the response. 
        baseQuery.save(RefreshMode.REFRESH);
        
        // retrieve the response to above query question
        String response = baseQuery.getProperties().getStringValue("GenaiLLMResponse");
    	
    	System.out.println( " --BaseLLMQuery response : " + response );

	}
}
```

--------------------------------

### Get OCP Routes using oc CLI

Source: https://www.ibm.com/docs/en/cacms/1.0.x/index_topic=service-accessing-your-deployment

This command retrieves all available routes for a specified project deployed on OpenShift Container Platform (OCP). It requires `oc` CLI access to the cluster. The output lists the hostnames and paths for various services.

```bash
oc get routes
```

--------------------------------

### Deploy IBM Content Assistant Operator (Python - Silent)

Source: https://www.ibm.com/docs/en/cacms/1.0.x/index_topic=operator-installing-by-running-script

Executes the operator deployment script in silent mode, allowing for automated or non-interactive deployments. Configuration is typically provided via command-line arguments or environment variables.

```python
python3 deploy_operator.py --silent
```

--------------------------------

### Get CNCF Ingress using kubectl CLI

Source: https://www.ibm.com/docs/en/cacms/1.0.x/index_topic=service-accessing-your-deployment

This command fetches ingress resources for a project deployed on a Cloud Native Computing Foundation (CNCF) environment, typically managed by Kubernetes. It requires `kubectl` CLI access. The output details the ingress points for services.

```bash
kubectl get ingress
```

--------------------------------

### List Downloaded CASE Files

Source: https://www.ibm.com/docs/en/cacms/1.0.x/index_topic=environment-optional-downloading-case-package-manually

This command lists all CASE files that have been successfully downloaded to the host. It confirms the presence of downloaded CASE files in the specified directory and provides the location of log files for troubleshooting.

```bash
oc ibm-pak list --downloaded
```

--------------------------------

### Get Kubernetes Events (Kubectl)

Source: https://www.ibm.com/docs/en/cacms/1.0.x/index_topic=support-troubleshooting-container

This command retrieves a list of Kubernetes events, which provide insights into cluster activities such as scheduler decisions or pod evictions. The output is redirected to an 'events.log' file for easier analysis.

```bash
kubectl get events > events.log
```

--------------------------------

### Python Script for Image Mirroring: Interactive Execution

Source: https://www.ibm.com/docs/en/cacms/1.0.x/index_topic=pycagodo-downloading-case-packages-mirroring-images-in-airgap-environment

Demonstrates how to run the load_images.py script in interactive mode, enabling OCP Airgap mode by default. This allows the user to specify settings during script execution.

```bash
python3 load_images.py --airgap
```
Tokens:
Raw