Installing operators

Operators available to install

You can install any combination of operators. Any dependencies will be pulled in automatically.

IBM Cloud Pak for Integration

Top level Cloud Pak for Integration operator that will install all other Cloud Pak for Integration operators automatically. Use this to install the whole Cloud Pak in one operation.

IBM Cloud Pak for Integration Platform Navigator

Provides a dashboard and central services for other Cloud Pak for Integration capabilities. Should be installed for most Cloud Pak for Integration installations.

IBM Cloud Pak for Integration Asset Repository

Stores, manages, retrieves and searches for integration assets for use within the IBM Cloud Pak for Integration and its capabilities.

IBM Cloud Pak for Integration Operations Dashboard

Transaction tracing across capabilities and runtimes to allow troubleshooting and investigation of errors and latency issues across integration capabilities to ensure applications meet service level agreements.

IBM Cloud Pak for Integration Demos

Allows you to deploy demos that showcase the capabilities available in Cloud Pak for Integration.

IBM API Connect

Provides the API management and Event Endpoint Management capabilities.

IBM App Connect

Provides application integration capabilities and a means to easily create and export flows that run in an App Connect instance.

IBM Aspera HSTS

Provides high speed transfer integration capabilities.

IBM DataPower Gateway

Provides gateway capabilities.

IBM MQ

Provides messaging capabilities.

Installation methods

There are two methods for installing operators:

• Openshift web console

• oc command-line tool (CLI)

Red Hat OpenShift console

1. Open the OpenShift console.

2. Make sure you have selected the Administrator view (rather than the Developer view).

   

3. Click Operators > OperatorHub > Integration & Delivery.

4. Click the tile for the operator you want to install, for example, IBM Cloud Pak for Integration.

5. Click Install.

6. In the Install Operator pane:

   • Select the desired operator channel. See Operator channel versions for IBM Cloud Pak for Integration releases for more information.

   • Select the option to install Cloud Pak for Integration in one namespace or in all namespaces in your cluster. See "Guidelines for installing operators" below for more information.

   • Select an approval strategy. You can select the automatic or manual option. For more information about a manual approval strategy, see Restricting automatic updates with an approval strategy.

7. Click Install.

oc command-line tool (CLI)

1. Only if your desired installation mode is a specific namespace on the cluster, create an OperatorGroup similar to the example below. Replace <namespace> with your desired namespace.

apiVersion: operators.coreos.com/v1
kind: OperatorGroup
metadata:
  name: ibm-integration-operatorgroup
  namespace: <namespace>
spec:
  targetNamespaces:
  - <namespace>

1. Create a Subscription similar to the example below for the IBM Cloud Pak for Integration operator. Replace <namespace> with:

   • openshift-operators, if installing the operator in All namespaces on the cluster.

   • Your chosen namespace, if installing in A specific namespace on the cluster.

apiVersion: operators.coreos.com/v1alpha1
kind: Subscription
metadata:
  name: ibm-cp-integration
  namespace: <namespace>
spec:
  channel: v1.2
  name: ibm-cp-integration
  source: ibm-operator-catalog
  sourceNamespace: openshift-marketplace
  ```

## Guidelines for installing operators

For additional details and deployment recommendations, see [deployment-considerations].

>**Note:** OpenShift restricts the use of default namespaces for installing non-cluster services. The following namespaces cannot be used to install [product-short] operators: `default`, `kube-system`, `kube-public`,`openshift-node`, `openshift-infra`, `openshift`.

When installing Cloud Pak for Integration operators, follow these guidelines:
- Typically, a *cluster administrator* installs the operators, and an *automation administrator* creates the customer resources (installed instance of the operator) and configures the capabilities and runtimes. See [admin-roles] for more information.
- Operators can be installed at cluster scope (in all namespaces in the cluster) or at namespace scope (in an individual namespace).
- If the operators are installed at cluster scope, the entire cluster effectively behaves as one large tenant.
- If the operators are installed at namespace scope, each namespace effectively behaves as a different tenant.   
- Cloud Pak for Integration can be installed in either of two installation modes: **All namespaces on the cluster** or **A specific namespace on the cluster**.
- All IBM Cloud Paks installed in a cluster must be installed in the same mode, whether **All namespaces on the cluster** or **A specific namespace on the cluster**. If you are installing one of more Cloud Paks with Cloud Pak for Integration, you can't use both mode types together.
- When Cloud Pak for Integration is installed in the **All namespaces on the cluster** installation mode, there can be only one Platform Navigator per cluster, and all Cloud Pak instances are owned by that Platform Navigator.
- When [product-short]is installed in **A specific namespace on the cluster** mode, there can be one Platform Navigator in each namespace, and that Platform Navigator owns only the instances in that namespace.
- When operators are installed in the **All namespaces on the cluster** installation mode, the operator must be installed in the **openshift-operators** namespace.
- For both installation modes, by default a single instance of [cs] is installed in the `ibm-common-services` namespace if the [cs-short] operator is not already installed on the cluster. The [cs-short] operator must be installed in the same mode as the Cloud Pak operators. However, regardless of the mode with which it is installed, by default the [cs-short] operator will install the **Operand Deployment Lifecycle Manager** operator in the **A specific namespace on the cluster** mode in the `ibm-common-services` namespace. While the **Operand Deployment Lifecycle Manager** operator is installed in this mode, it will extend its permissions to manage [cs-short] resources in all the namespaces where capabilities and runtimes of the Cloud Pak are installed. To use a custom namespace for [cs-short], see [cs-custom-namespace] before installing [product-short] operators.
- When [product-short] is installed in either mode, operators still need a small set of cluster level permissions to allow manipulation of resources defined at cluster scope, such as reading Custom Resource Definitions. See [cluster-scoped-permissions] for information about the permissions required.
- If you need the entire Cloud Pak for Integration (or only certain of its capabilities and runtimes) to use manual approval&mdash;and not update automatically&mdash;see [Restricting automatic updates with an approval strategy](#restricting-automatic-updates-with-an-approval-strategy).

## Validating an installed operator

To validate a operator has installed, navigate to the `Installed Operators` menu item in the OpenShift console. Select the project the operator was installed in. If you installed the operator using the **All namespaces on the cluster** installation mode, the operator will be located in the `openshift-operators` project.

Locate your Operator in the table and look at the `status` column. When the Operator is ready, it will say `Succeeded`.

To check the progress of operator deployment, you can look at the operator pod within the selected namespace using the `oc` command-line tool or the Openshift console.


## Restricting automatic updates with an approval strategy

Operators can be upgraded automatically when new compatible versions are available. However, in some situations this automatic upgrade may be undesirable. You can control whether or not an operator is upgraded automatically by setting an approval strategy, either:
* When the operator is installed.
* After installation, by modifying its subscription.

The available approval strategies are:
* **Automatic** (default): As new operator versions are made available on the subscription channel, they are installed automatically.
* **Manual**: As new operator versions are made available on the subscription channel, the subscription indicates that there is an update available, but you have to approve the update manually.

<note>When installing the **IBM Cloud Pak for Integration** operator, you may choose to install it with **Manual** approval. However, that approval setting only controls the behavior of the **IBM Cloud Pak for Integration** operator. *It does not affect the approval modes of the other operators that are installed, all of which will default to Automatic approval*. If you wish to modify the behavior of an operator, you must modify the **Subscription** of that operator individually. There is no way to modify the approval strategy of all Cloud Pak for Integration operators simultaneously.</note>


**Using the OpenShift console**

To confirm or update the approval strategy for an operator in the OpenShift console:
1. Expand the **Operators** section in the navigation bar on the left, and select **Installed Operators**. Ensure you select the project that contains the operators you want  to confirm or modify.
2. Click the operator you want to confirm or modify.
3. Click the **Subscription** tab.
4. The **Subscription Details** at the top of the tab will show you the **Channel** referenced by the subscription, what the **Approval** strategy is, and what the **Upgrade Status** is.
 * If the **Approval** strategy is set to **Automatic**, the **Upgrade Status** should show **Up to date**.
 * If the **Approval** strategy is set to **Manual**, the **Upgrade Status** may show **Upgrade available**. In this case, there may be an available control that allows you to approve the **InstallPlan** that upgrades the operator.

You can also change the approval strategy by clicking the **Subscription** tab, then selecting the **Approval** strategy value.  A **Change Update Approval Strategy** dialog appears and allows you to select a different strategy.


**Using the OpenShift CLI**

If you have both the OpenShift CLI with `oc` and the [jq](https://stedolan.github.io/jq/) JSON stream editor installed, you can confirm or update the approval strategy for all subscriptions in a specific project/namespace. To do so,  use the `oc` command in a `bash` shell:
```bash
NAMESPACE=<your namespace>
subscriptions=$(oc get subscription -n $NAMESPACE -o name)
for subscription in ${subscriptions}; do
echo -n "${subscription} "
oc get ${subscription} -n $NAMESPACE -o json | jq '.spec.installPlanApproval'
done

• If you have IBM operators installed across different namespaces, you can obtain a list of all subscriptions and their namespaces with:

oc get subscription --all-namespaces -o custom-columns=NAME:.metadata.name,NAMESPACE:.metadata.namespace \
  | grep 'ibm-' \
  | xargs -n2 sh -c 'printf "$0 $1: " && oc get subscription "$0" -n "$1" -o json | jq ".spec.installPlanApproval"'

This returns a row for each subscription, containing the subscription name, its namespace, and the approval strategy. For example:

ibm-cert-manager-operator ibm-common-services: "Automatic"
ibm-common-service-operator ibm-common-services: "Automatic"
ibm-commonui-operator ibm-common-services: "Automatic"
...
ibm-cp-integration cp4i: "Manual"
...

Pinning IBM Cloud Pak foundational services to a specific version

If you followed the procedure for IBM Cloud Pak foundational services in Adding online catalog sources to your OpenShift cluster, the CatalogSource will reference the latest published version:

apiVersion: operators.coreos.com/v1alpha1
kind: CatalogSource
metadata:
  name: opencloud-operators
  namespace: openshift-marketplace
spec:
  displayName: IBMCS Operators
  publisher: IBM
  sourceType: grpc
  image: docker.io/ibmcom/ibm-common-service-catalog:latest
...

To guarantee a manual approval process, the image should be pinned to a specific foundational services catalog version. You can check which catalog version is being in the OpenShift console as follows:

• Navigate to Installed Operators in OpenShift Console. To get here, expand the Operators section in the navigation bar on the left and select Installed Operators. Ensure you have selected the project that contains the operators you want to check or edit.

You can see a list of catalog sources with:

oc get catalogsource -n openshift-marketplace

This will return something similar to:

NAME                   DISPLAY               TYPE   PUBLISHER   AGE
certified-operators    Certified Operators   grpc   Red Hat     46h
community-operators    Community Operators   grpc   Red Hat     46h
ibm-operator-catalog                         grpc   IBM         28h
opencloud-operators    IBMCS Operators       grpc   IBM         46h
redhat-marketplace     Red Hat Marketplace   grpc   Red Hat     46h
redhat-operators       Red Hat Operators     grpc   Red Hat     46h

The foundational services catalog source will have the name specified by Adding online catalog sources to your OpenShift cluster i.e. opencloud-operators. You can check the referenced image with:

oc get catalogsource opencloud-operators -n openshift-marketplace -o json | jq '.spec.image'
>>> "docker.io/ibmcom/ibm-common-service-catalog:latest"

This can be patched to point to a specific image version:

oc patch catalogsource opencloud-operators -n openshift-marketplace --type='json' \
  -p '[{ "op": "replace", "path": "/spec/image", "value": "quay.io/opencloudio/ibm-common-service-catalog:3.5.6"}]'