Installing operators

Install operators for API Connect, DataPower, and common services so that you can deploy the API Connect subsystems.

1. Obtain an entitlement key for the Entitled Registry:
   1. Log in to the IBM Container Library.
   2. In the Container software library, select Get entitlement key.
   3. After the Access your container software heading, click Copy key.
   4. Copy the key to a safe location.
2. Create a global pull secret:
   1. Open the OpenShift web console, click Workloads > Secrets.
   2. Select the project openshift-config.
   3. Select pull-secret from the secret list.
   4. Select Actions > Edit Secret > Add Credentials.
   5. Set Registry Server Address to cp.icr.io.
   6. Set username to cp.
   7. Set Password to the entitlement key generated in Step 1.
   8. Click Save.
      Note: On OpenShift v4.6 the cluster nodes will restart as part of this step.
3. Add the IBM Common Services Catalog source:
   1. Open the OpenShift web console, and click + (in the page banner) to open the Import YAML dialog box.
   2. Paste the following resource definition into the dialog box:

      apiVersion: operators.coreos.com/v1alpha1
      kind: CatalogSource
      metadata:
        name: opencloud-operators
        namespace: openshift-marketplace
      spec:
        displayName: IBMCS Operators
        publisher: IBM
        sourceType: grpc
        image: quay.io/opencloudio/ibm-common-service-catalog:latest
        updateStrategy:
          registryPoll:
            interval: 45m

   3. Click Create.
4. Add the IBM Operator Catalog source:
   1. In the OpenShift web console, and click + (in the page banner) to open the Import YAML dialog box.
   2. Paste the following resource definition into the dialog box:

      apiVersion: operators.coreos.com/v1alpha1
      kind: CatalogSource
      metadata:
        name: ibm-operator-catalog
        namespace: openshift-marketplace
      spec:
        displayName: "IBM Operator Catalog" 
        publisher: IBM
        sourceType: grpc
        image: icr.io/cpopen/ibm-operator-catalog
        updateStrategy:
          registryPoll:
            interval: 45m

   3. Click Create.
5. Create the namespace where API Connect will be installed, either by selecting Project->Create Project in the UI, or via the command line:

   oc create ns <APIC-namespace>

   The namespace where you install API Connect must meet the following requirements:

   • OpenShift restricts the use of default namespaces for installing non-cluster services. The following namespaces cannot be used to install API Connect: default, kube-system, kube-public, openshift-node, openshift-infra, openshift.
   • OpenShift: Only one top-level CR (APIConnectCluster) can be deployed in each namespace.
   • Cloud Pak for Integration: Only one API Connect capability can be deployed in each namespace.
6. If you are installing the operator into a single namespace, create an OperatorGroup object.
   Attention: If you are installing the operator into all namespaces, skip this step because the openshift-operators namespace already has an appropriate Operator group in place.
   1. Create the apiconnect-operator-group.yaml file with an OperatorGroup object that identifies the namespace in which RBAC permissions for the IBM API Connect Operator will be generated, and where the CSV will be available:

      apiVersion: operators.coreos.com/v1
      kind: OperatorGroup
      metadata:
        name: <operator-group-name>
        namespace: <APIC-namespace>
      spec:
        targetNamespaces:
        - <APIC-namespace>

   2. Apply the OperatorGroup object with the following command:

      oc apply -f apiconnect-operator-group.yaml

7. Create the apiconnect subscription.
   1. Create the apiconnect subscription with the appropriate channel:

      apiVersion: operators.coreos.com/v1alpha1
      kind: Subscription
      metadata:
        name: ibm-apiconnect
        namespace: <set to 'openshift-operators' if step 6 not done, otherwise set to the namespace created in step 5>
      spec:
        channel: v2.1.12-eus
        installPlanApproval: Manual
        name: ibm-apiconnect
        source: ibm-operator-catalog
        sourceNamespace: openshift-marketplace

      Warning: Do not set installPlanApproval: Automatic. If set to Automatic then the operator updates automatically whenever a newer API Connect interim fix is available within the selected channel. When the API Connect operator is updated then all API Connect subsystems must be updated, which is a manual operation. When set to Manual a notice displays that a new version is available and gives the option to upgrade.
   2. Apply the subscription with the following command:

      oc apply -f apic-sub.yaml

      If the operator was installed into the namespace that is created in step 5, select that namespace under 'Project'. Otherwise, select the project openshift-operators.

      If the API Connect operator shows the status of 'Upgrade available' then approve the upgrade as follows:

      1. Click 'Upgrade available'.
      2. Click 'Preview InstallPlan'.
      3. Click 'Approve'.

      Wait for IBM API Connect, IBM DataPower Gateway, and IBM Common Service Operator operators to install. The IBM DataPower Gateway operator is a prerequisite to API Connect and must not be removed.

      Note: There is a known issue on Kubernetes version 1.19.4 or higher that can cause the DataPower operator to fail to start. In this case, the DataPower Operator pods can fail to schedule, and will display the status message: no nodes match pod topology spread constraints (missing required label). For example:

      0/15 nodes are available: 12 node(s) didn't match pod topology spread constraints (missing required label), 
      3 node(s) had taint {node-role.kubernetes.io/master: }, that the pod didn't tolerate.

      You can workaround the issue by completing the following steps to replace the operator with a newer version:

      1. Uninstall the DataPower operator deployment:
         1. In the OpenShift Form UI, click Operators > Installed Operators.
         2. Type datapower in the Filter by name field (or scroll until you locate the operator).
         3. Select the operator and click Actions > Uninstall Operator.
      2. Get a newer version of the operator by downloading and decompressing the IBM API Connect release files from IBM Fix Central:

         apiconnect-operator-release-files_version.zip

      3. Install the newer DataPower operator by running the following command:

         oc apply -f ibm-datapower.yaml