Installing or updating a connector

IBM Cloud Pak® for Security includes some connectors, but more are available on IBM® X-Force® Exchange / App Exchange. Install connectors from IBM X-Force Exchange / App Exchange to add new connectors to your Cloud Pak for Security deployment, or to update existing connectors to the latest version.

Follow these steps to upgrade and install your connection, regardless of how you installed Cloud Pak for Security, including installing from the IBM Cloud® catalog.

Important: You can install a connector only in on-premises installations of Cloud Pak for Security.

Before you begin

- For Connected Assets and Risk connectors, set the Content Type to Assets and Risks.
- For Universal Data Insights connectors, set the Content Type to Federated Search.

1. Download Cloud Pak CLI from https://github.com/IBM/cloud-pak-cli/releases.
2. Extract the binary file that you downloaded by typing the following command, where <cloud_pak_cli_archive_file> is the name of the archive file that you downloaded.
```
tar -xf <cloud_pak_cli_archive_file>
```
3. Modify the permissions of the binary file by typing the following command, where <cloud_pak_cli_binary> is the name of the Cloud Pak binary file that you extracted from the archive.
```
chmod 755 <cloud_pak_cli_binary>
```
4. Move the binary file to the /usr/local/bin directory by typing the following command.
```
mv <cloud_pak_cli_binary> /usr/local/bin/cloudctl
```
5. Ensure that Cloud Pak CLI is working by typing the following command.
```
cloudctl version
```
  Tip: MacOS users might see a message that this tool cannot be opened because it is from an unidentified developer. Close this message and go to System Preferences > Security & Privacy. On the General tab, click Open Anyway or Allow Anyway. Repeat the cloudctl version command.

The Red Hat OpenShift CLI client helps you develop, build, deploy, and run your applications on any Red Hat OpenShift or Kubernetes cluster. It also includes the administrative commands for managing a cluster under the adm subcommand.
1. Download Red Hat OpenShift CLI 4.8 or later from https://mirror.openshift.com/pub/openshift-v4/x86_64/clients/ocp/stable-4.8/. The file to download is called openshift-client-<platform>-<version>.tar.gz.
2. Extract the binary file that you downloaded by typing the following command, where <oc_cli_archive_file> is the name of the archive file that you downloaded.
```
tar -xf <oc_cli_archive_file>
```
3. Modify the permissions of the binary file by typing the following command, where <oc_cli_binary> is the name of the Red Hat OpenShift binary that you extracted from the archive.
```
chmod 755 <oc_cli_binary>
```
4. Move the binary file to the /usr/local/bin directory by typing the following command.
```
mv <oc_cli_binary> /usr/local/bin/oc
```
  Tip: If this command returns a No such file or directory or Not a directory error message, create the /usr/local/bin directory by typing the following command.
```
sudo mkdir /usr/local/bin
```
5. Ensure that the Red Hat OpenShift CLI client is working by typing the following command.
```
oc version
```
  Tip: MacOS users might see a message that this tool cannot be opened because it is from an unidentified developer. Close this message and go to System Preferences > Security & Privacy. On the General tab, click Open Anyway or Allow Anyway. Repeat the oc version command.

Procedure

Download the Cloud Pak for Security archive file and extract it locally.
1. Create and go to the cp4s_install working directory by typing the following command.
```
export CP4S_DIR=$HOME/cp4s_install
mkdir $CP4S_DIR && cd $CP4S_DIR
```
  Important: If you already installed a version of cp4s_install in your $HOME directory, before you run the command you must rename or delete the directory.
2. Download and extract the Cloud Pak for Security archive file by typing the following command.
```
cloudctl case save \
  --repo https://github.com/IBM/cloud-pak/raw/master/repo/case \
  --case ibm-cp-security \
  --version 1.0.29 \
  --outputdir $CP4S_DIR \
  -t 1 \
  && tar -xf $CP4S_DIR/ibm-cp-security-1.0.29.tgz
```
Log in to your cluster by using either of the following commands.
- Using a username and password.
```
oc login <openshift_url> -u <username> -p <password>
```
- Using a token.
```
oc login --token=<token> --server=<openshift_url>
```

Find your Cloud Pak for Security namespace by typing the following commands.

NAMESPACE=$(oc get pod -lname=cp4s-extension --all-namespaces --no-headers | awk '{print $1}')

echo $NAMESPACE

Run the deploy-connector action by typing one of the following commands.

In an online environment:

cloudctl case launch -t 1 --case $CP4S_DIR/ibm-cp-security --inventory ibmSecurityOperatorSetup --namespace $NAMESPACE --action deploy-connector --args "--type <car_or_udi> --connector_image <connector_image>"

In an air-gapped environment:

cloudctl case launch -t 1 --case $CP4S_DIR/ibm-cp-security --inventory ibmSecurityOperatorSetup --namespace $NAMESPACE --action deploy-connector --args "--type <udi_or_car> --connector_image <connector_image> --registry ${LOCAL_DOCKER_REGISTRY}:5000"

The following arguments are required in the deploy-connector action.

Argument	Description
--type	The type of connector that you want to install. This value must be either `udi` or `car`.
--connector_image	The connector image that you want to install. A certified connector is hosted on the IBM Cloud Container Registry and has the format: icr.io/ibm-cp-security/`<image_name>`:`<tag>`. The tag of a certified connector has the format: `<connector_version>`. An example image: icr.io/ibm-cp-security/stix_shifter_modules_qradar:3.3.12 You can find the connector image in the Installation section of the connector description on IBM X-Force Exchange / App Exchange.
--registry	Air-gapped environment only. The local Docker registry.

In an online environment, the connector image is deployed into the cluster.

In an air-gapped environment, the connector image is mirrored from the public registry into the local Docker registry and deployed it into the cluster.

If the command outputs the following error, verify the connector image name and tag, then try again.

[ERROR] Cannot pull image icr.io/ibm-cp-security/<image_name>:<tag>. Make sure it exists.

If the command outputs the following error, you must upgrade Cloud Pak for Security to a version that supports the connector before you can install it.

[ERROR] The image compatible with the following version(s) '<later_version_1>, <later_version_2>' but not with the current application version <current_version>

If the command outputs the following warning, the connector doesn't contain information about which versions of Cloud Pak for Security support the connector. The connector might install, but might not work with your version of Cloud Pak for Security.

[WARNING] 'compatibleReleases' label not found in the image labels

Verify that the connector is deployed.
1. Display a list of installed connectors by typing the following command.
```
cloudctl case launch -t 1 --case $CP4S_DIR/ibm-cp-security --inventory ibmSecurityOperatorSetup --namespace $NAMESPACE --action list-connectors
```
2. Verify the connector version by typing the following command and viewing the specification in the output.
```
cloudctl case launch  -t 1 --case $CP4S_DIR/ibm-cp-security --inventory ibmSecurityOperatorSetup --namespace $NAMESPACE --action get-connector --args "--name <connector_name>" | grep image
```
  The following arguments are required in the get-connector action.
  
  Argument Description
  
  --name The name of the connector as shown in the list that is returned by running the list-connectors action.
  The connector version shows as part of the image tag that gets returned. For example, the connector version 3.3.12 can be seen in icr.io/ibm-cp-security/stix_shifter_modules_qradar:3.3.12. The connector version can be used to verify whether the connector is updated.
If you no longer need a connector, delete it from your cluster.
1. Display a list of installed connectors by typing the following command.
```
cloudctl case launch -t 1 --case $CP4S_DIR/ibm-cp-security --inventory ibmSecurityOperatorSetup --namespace $NAMESPACE --action list-connectors
```
2. Delete a connector by typing the following command.
```
cloudctl case launch  -t 1 --case $CP4S_DIR/ibm-cp-security --inventory ibmSecurityOperatorSetup --namespace $NAMESPACE --action delete-connector --args "--name <connector_name>"
```
  The following arguments are required in the delete-connector action:
  
  Argument Description
  
  --name The name of the connector as shown in the list that is returned by running the list-connectors action.

Argument	Description
--name	The name of the connector as shown in the list that is returned by running the list-connectors action.

Argument	Description
--name	The name of the connector as shown in the list that is returned by running the list-connectors action.

What to do next

If your connector is from the IBM X-Force Exchange / App Exchange, you must reinstall your connector to avoid compatibility issues when Cloud Pak for Security is updated.

If you have connectors that are included in the Cloud Pak for Security release package, they are automatically updated when Cloud Pak for Security is updated.