Installing operators

Important: Before installing any IBM Cloud Pak® for Integration operators, you must install the IBM Cloud Pak foundational services operator using the stable-v1 channel in order to qualify for Extended Update Support. For more details see the Extended Update Support (EUS) section below.

IBM Cloud Pak for Integration operators are installed and managed using the Operator Lifecycle Manager (OLM) in Red Hat OpenShift. After the operators are installed, you can use them to deploy Cloud Pak for Integration components.

Operators extend a Kubernetes cluster by adding and managing additional resource types in the Kubernetes API. For more information, see Understanding Operators in the Red Hat OpenShift documentation.

You can install all of the Cloud Pak operators at once by using the IBM Cloud Pak for Integration operator, or install a subset of operators by selecting and installing only the operators you need to use on your cluster. When installing an operator, OLM automatically installs any required dependencies.

If you don't explicitly set the profile of IBM Cloud Pak foundational services before installing IBM Cloud Pak for Integration components, the medium profile of common services will be used. If you install common services using the large or medium profile, you cannot scale down the profile to small after installation. See Setting the common services profile for more information and instructions on setting the small profile.

Installation methods

For detailed instructions on how to install an operator, see Adding Operators to a cluster in the Red Hat OpenShift documentation.

There are two methods for installing operators:

Red Hat OpenShift console.
1. Open the OpenShift console.
2. At the top of the left navigation panel, make sure you have selected Administrator (rather than Developer), then click Operators > OperatorHub > Integration & Delivery.
3. Click the tile for the operator you want to install, for example, IBM Cloud Pak for Integration.
4. Click Install.
5. 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.
6. Click Install.
Use the oc command-line tool (CLI). For more information, see Getting started with the CLI in the Red Hat OpenShift documentation.

When using the CLI, you need to:
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>
```
2. 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.1-eus
  name: ibm-cp-integration
  source: ibm-operator-catalog
  sourceNamespace: openshift-marketplace
```

Guidelines for installing CP4I operators

For additional details and deployment recommendations, see Considerations for structuring your installation.

When installing CP4I operators, follow these guidelines:

Typically, a cluster admin installs the operators, and a namespace admin creates the customer resources (installed instance of the operator) and configures the components.
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 CP4I, 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 Cloud Pak for Integration 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, a single instance of IBM Cloud Pak foundational services is installed in the ibm-common-services namespace if the common services operator is not already installed on the cluster. Ensure any existing installation meets the minimum system requirements for the Cloud Pak listed in Compute resources for development environments.
The common services operator must be installed in the same mode as the Cloud Pak operators. However, regardless of the mode with which it is installed, the common services 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 common services resources in all the namespaces where components of the Cloud Pak are installed.
When Cloud Pak for Integration 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 components of it) to use manual approval—and not update automatically—see Restricting automatic updates with an approval strategy.

Extended Update Support (EUS)

If you want to qualify for Extended Update Support (rather than Continuous delivery (CD) support) there are restrictions on how your operators can be installed. See here for more information.

EUS is only offered when installing on OCP 4.6. Moving to a different version of OCP changes support back to CD support.

In order to have an EUS version of IBM Cloud Pak foundational services, you must have the operator channel for the common services operator set to stable-v1, and you must be at version 3.6.2 or later of the operator.

When installing an operator, you are required to select the channel that will be used for future updates. To use EUS version of a CP4I component, select the channel suffixed with -eus.

For a CP4I installation to be eligible for extended update support, all components must be installed using EUS operators. If you install a mix of EUS operators and standard operators, all components will follow the standard support lifecycle.

Each operator provides an EUS-specific operand, which should also be used.

For CP4I 2020.4.1,the operators will pull in versions of dependencies that must be used to qualify for EUS.

Important: You should not change the versions of these dependencies manually unless instructed to by IBM support.

In summary, to qualify for EUS, ensure that:

You are running on OCP 4.6.
For IBM Cloud Pak foundational services, you set the operator channel to stable-v1 and you use v. 3.6.2 or later of the operator.
You use the EUS version of the operators.
You use the EUS-specific operands provided by these operators.
You do not modify the version of the dependencies installed by the EUS operators.

Continuous Delivery (CD) Support

You can install IBM Cloud Pak for Integration version 2020.4 into an OCP 4.7 cluster using common services 3.7.x.

Note: Your common services operator must be installed at namespace scope (in a single namespace).

Create a namespace called ibm-common-services.
In ibm-common-services, do one of the following:
- Install common services 3.7.x.
- Upgrade an existing namespace-scoped instance of common services 3.6.x.
Create a namespace (for example, cp4i) for your Cloud Pak for Integration installation.
Install all desired Cloud Pak for Integration operators in your new namespace.

Operators available to install

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

Note: A "(Z)" next to a component indicates that it is available on Linux for IBM Z.

IBM Cloud Pak for Integration: Top level CP4I operator that will install all other CP4I operators automatically. Use this to install the whole Cloud Pak in one operation.
IBM Cloud Pak for Integration Platform Navigator (Z): Provides a dashboard and central services for other CP4I capabilities. Should be installed for most CP4I 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: Cross-component transaction tracing to allow troubleshooting and investigation of errors and latency issues across integration capabilities to ensure applications meet service level agreements.
IBM API Connect: Provides API management capabilities.
IBM App Connect (Z - Dashboard, not Designer): Provides application integration capabilities and a means to easily create and export flows that run in an App Connect instance.
IBM Aspera HSTS (Z): Provides high speed transfer integration capabilities.
IBM Datapower Gateway: Provides gateway capabilities.
IBM Event Streams (Z): Provides IBM Event Streams capabilities.
IBM MQ (Z): Provides messaging capabilities.

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 CP4I operators simultaneously.

Using the OpenShift console

To confirm or update the approval strategy for an operator in the OpenShift console:

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.
Click the operator you want to confirm or modify.
Click the Subscription tab.
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 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:

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"
...

CAUTION:

You should not change the approval strategy for IBM Cloud Pak foundational services operators as this may cause unexpected behavior in future upgrades. If you want to manually upgrade common services operators in future, you should pin common services to a specific version as described in the next section.

Pinning IBM Cloud Pak foundational services to a specific version

If you followed the procedure for IBM Cloud Pak foundational services in Adding the online catalog sources to a 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 common 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 common services catalog source will have the name specified by Adding the online catalog sources to a 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"}]'