Installing operators

Install operators for API Connect, DataPower, and common services so that you can deploy the API Connect subsystems in a shared namespace on OpenShift.

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 the namespace where API Connect will be installed, either by selecting Home->Projects->Create Project in the UI, or with the command:

   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.
3. If you are installing the operator into a single namespace, create an OperatorGroup object specifying that namespace.
   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

4. Create the image pull secret in the namespace where you want to install API Connect:
   1. Open the OpenShift web console, click Workloads > Secrets.
   2. Ensure that the Project is set to the namespace where you intend to install API Connect.
   3. Click Create and select Image pull secret.
   4. Set the following parameters for the secret:
      • Set Secret name to ibm-entitlement-key.
      • Set Authentication type to Image registry credentials.
      • Set Registry server address to cp.icr.io.
      • Set Username to cp.
      • Set Password to the entitlement key generated in Step 1.
      • Click Create to create the secret.
   Note: If your OpenShift platform is Red Hat OpenShift on IBM Cloud (ROKS), you might need to reload your worker nodes after the image pull secret is created. You can reload the worker nodes either from the OpenShift web console or from the command line with: oc worker reload.
5. 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.
6. Create the apiconnect subscription.
   1. Create the apiconnect subscription with the appropriate channel by creating a file called apic-sub.yaml and pasting in the following contents, updating the namespace as required:

      apiVersion: operators.coreos.com/v1alpha1
      kind: Subscription
      metadata:
        name: ibm-apiconnect
        namespace: <namespace>
      spec:
        channel: v3.8
        name: ibm-apiconnect
        source: ibm-operator-catalog
        sourceNamespace: openshift-marketplace

      Where:

      • <namespace> is set to openshift-operators if you are installing the API Connect operator in all namespaces. Otherwise set this to the namespace created in step 2.
   2. Apply the subscription with the following command:

      oc apply -f apic-sub.yaml

   3. Select Operators > Installed Operators, and ensure that Project: All Projects is selected.

      If any operators such as ibm-apiconnect or ibm-cert-manager-operator show the status of "Upgrade available", approve the upgrade by completing the following steps:

      1. Click Upgrade available.
      2. Click Preview InstallPlan.
      3. Click Approve.
      4. Wait for the IBM API Connect and IBM DataPower Gateway operators to install.

      The IBM DataPower Gateway operator is a prerequisite to API Connect and must not be removed.

7. (10.0.5.3 and later) Create the ibm-common-services-operator subscription, if it does not already exist.

   This step only applies when you install version 10.0.5.3 or later. If you are installing an older version of API Connect, skip this step.

   1. Create a file called common-services-sub.yaml and paste in the following contents:

      apiVersion: operators.coreos.com/v1alpha1
      kind: Subscription
      metadata:
        name: ibm-common-service-operator
        namespace: <namespace>
      spec:
        channel: <channel>
        name: ibm-common-service-operator
        source: ibm-operator-catalog
        sourceNamespace: openshift-marketplace

      Where:

      • <namespace> is one of the following values:
        • openshift-operators if you are installing the API Connect operator in all namespaces
        • The namespace created in step 2 if you are installing the API Connect operator in a single namespace
      • <channel> is one of the following values:
        • v3.23 if you are using IBM Cloud Pak foundational services for CD (continuous delivery)
        • v3 if you are using IBM Cloud Pak foundational services for LTSR (long term service release)
   2. Apply the subscription with the following command:

      oc apply -f common-services-sub.yaml

   3. Select Operators > Installed Operators, and ensure that Project: All Projects is selected.

      If any operators such as ibm-apiconnect or ibm-cert-manager-operator show the status of "Upgrade available", approve the upgrade by completing the following steps:

      1. Click Upgrade available.
      2. Click Preview InstallPlan.
      3. Click Approve.
      4. Check the ibm-common-services namespace and ensure that all operators with a status of "Upgrade available" are approved.
      5. Wait for the IBM Cloud Pak foundational services, IBM NamespaceScope, and Operand Deployment Lifecycle Manager operators to install.
8. (10.0.5.3 and later) Install cert manager:

   This step only applies when you install version 10.0.5.3 or later. If you are installing an older version of API Connect, skip this step.

   1. Create a file called cert-manager-operand-request.yaml and paste in the following content:

      apiVersion: operator.ibm.com/v1alpha1
      kind: OperandRequest
      metadata:
        name: ibm-apiconnect-cert-manager
        namespace: <namespace>
      spec:
        requests:
        - operands:
          - name: ibm-cert-manager-operator
          registry: common-service
          registryNamespace: ibm-common-services

   2. Create the operandRequest for cert-manager by running the following command:

      oc apply -f cert-manager-operand-request.yaml

   3. Select Operators > Installed Operators, and ensure that Project: All Projects is selected.

      Wait for the ibm-cert-manager-operator to display and if it shows the status of "Upgrade available", approve the upgrade by completing the following steps:

      1. Click Upgrade available.
      2. Click Preview InstallPlan.
      3. Click Approve.
      4. Wait for the IBM Cert Manager operator to install.