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.

Before you begin

The API Connect operator and operand must be at compatible release and fix pack levels. Table 1 lists the current version of the operator and operand for API Connect.

Table 1. API Connect operator and operand versions
API Connect (operand) Operator channel version Highest operator version
10.0.9.0 v6.0 6.0.0
If you want to run API Connect operator and subsystems at different versions, the following table shows the supported combinations:
Table 2. API Connect versions supported by the API Connect operators.
API Connect Operator version API Connect version
6.0.0
  • 10.0.9.0
5.3.0
  • 10.0.8.1
  • 10.0.8.0
5.2.0
  • 10.0.8.0
Note: There can be only one instance of the API Connect operator in your OpenShift environment. You cannot have multiple namespaces each with their own API Connect operator.

The API Connect operator pods in your operator namespace must have network access to the namespace where your API Connect subsystems are installed. Do not configure OpenShift network policies that block communication between any of these namespaces:

  • API Connect operator
  • API Connect subsystems (operands)
  • cert-manager
  • openshift-operator-lifecycle-manager
  • ibm-common-services

Procedure

  1. Download the IBM Catalog Management Plug-in for IBM Cloud Paks version 1.1.0 or later from GitHub.
    Air-gapped: If you are in an air-gapped environment, then skip this step and instead follow the steps in Air-gapped installation, and then continue from step 3.

    The ibm-pak plug-in enables you to access hosted product images, and to run oc ibm-pak commands against the cluster. To confirm that ibm-pak is installed, run the following command and verify that the response lists the command usage:

    oc ibm-pak --help
  2. Obtain an entitlement key for the Entitled Registry:
    Air-gapped: If you are in an air-gapped environment, then skip this step and instead follow the steps in Air-gapped installation, and then continue from step 3.
    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.
  3. Create the namespace where API Connect will be installed, either by selecting Home > Projects > Create Project in the UI, or with the following command: 
    oc create ns <APIC-namespace>
    The namespace where you install API Connect must meet the following requirements:
    • Red Hat 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.
    • Red Hat 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
  4. 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
  5. If you are installing the operator in all namespaces, then create the common services namespace: 
    oc create ns ibm-common-services
  6. Create a pull secret in the namespaces where you want to install API Connect.
    Air-gapped: If you are in an air-gapped environment, then skip this step as it is covered in Air-gapped installation.
    1. Open the Red Hat 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 2.
      • Click Create to create the secret.
    Note: If your Red Hat 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 Red Hat OpenShift web console or from the command line with the following command: ibmcloud oc worker reload

    For information on using the reload command, see the Red Hat OpenShift on IBM Cloud documentation.

  7. Add the API Connect catalog sources to your cluster.
    Air-gapped: If you are in an air-gapped environment, then skip this step as it is covered in Air-gapped installation.

    Adding catalog sources to your Red Hat OpenShift cluster adds the IBM operators to the list of operators you can install. For most connected and air-gapped clusters, applying individual catalog sources is the most effective way to fully control software versioning on the cluster.

    1. Generate the catalog source files:
      1. Log into your cluster using the oc login command and your user credentials:
        oc login <openshift_url> -u <username> -p <password> -n <APIC-namespace>
      2. Export the variables for the command line to use:
        export CASE_NAME=ibm-apiconnect
export CASE_VERSION=6.0.0
export ARCH=amd64

        For information on API Connect CASE versions and their corresponding operators and operands, see Operator, CASE, and platform requirements.

      3. Download the files for the operators required by API Connect:
        oc ibm-pak get ${CASE_NAME} --version ${CASE_VERSION}
      4. Generate the catalog sources for API Connect:
        oc ibm-pak generate mirror-manifests ${CASE_NAME} icr.io --version ${CASE_VERSION}
      5. Optionally get the catalog sources and save them in another directory in case you need to replicate this installation in the future:

        Get the catalog sources:

        cat ~/.ibm-pak/data/mirror/${CASE_NAME}/${CASE_VERSION}/catalog-sources.yaml
    2. Apply the catalog sources:
      1. Apply the catalog sources:
        oc apply -f ~/.ibm-pak/data/mirror/${CASE_NAME}/${CASE_VERSION}/catalog-sources.yaml
      2. Confirm that the catalog sources have been created in the openshift-marketplace namespace:
        oc get catalogsource -n openshift-marketplace
  8. Add the IBM Cloud Pak foundational services (common services) catalog sources to your cluster.
    Air-gapped: If you are in an air-gapped environment, then skip this step as it is covered in Air-gapped installation.
    1. Generate the catalog source files:
      1. Log into your cluster using the oc login command and your user credentials:
        oc login <openshift_url> -u <username> -p <password> -n <APIC-namespace>
      2. Export the variables for the command line to use; substituting the appropriate CASE version:
        export CASE_NAME=ibm-cp-common-services
export CASE_VERSION=<case version>
export ARCH=amd64

        Set <case version> to the value specified for Foundational services CASE version in Operator, CASE, and platform requirements, for your deployment type.

      3. Download the files for the operators required by IBM Cloud Pak foundational services (common services):
        oc ibm-pak get ${CASE_NAME} --version ${CASE_VERSION}
      4. Generate the catalog sources:
        oc ibm-pak generate mirror-manifests ${CASE_NAME} icr.io --version ${CASE_VERSION}
      5. Optionally get the catalog sources and save them in another directory in case you need to replicate this installation in the future:

        Get the catalog sources:

        cat ~/.ibm-pak/data/mirror/${CASE_NAME}/${CASE_VERSION}/catalog-sources.yaml

        This command might not return anything if there are no architecture-specific catalog sources.

    2. Apply the catalog sources:
      1. Apply the catalog sources:
        oc apply -f ~/.ibm-pak/data/mirror/${CASE_NAME}/${CASE_VERSION}/catalog-sources.yaml
      2. Confirm that the catalog sources have been created in the openshift-marketplace namespace:
        oc get catalogsource -n openshift-marketplace
  9. 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: v6.0
  name: ibm-apiconnect
  source: ibm-apiconnect-catalog
  sourceNamespace: openshift-marketplace
      Where <namespace> is one of the following values:
      • openshift-operators if you are installing the operator in all namespaces
      • The namespace created in step 3 if you are installing the operator in a single namespace
    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 DataPower Gateway 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.

  10. Install cert manager by completing the following steps:
    1. Log in to the OpenShift Container Platform web console.

    2. Navigate to Operators > OperatorHub.

    3. In the filter box, type: cert-manager Operator for Red Hat OpenShift.

    4. Select cert-manager Operator for Red Hat OpenShift and click Install.

    5. On the Install Operator page, complete the following steps:
      1. Update the Update channel if needed. The channel defaults to stable-v1, which installs the latest stable release of the cert-manager Operator for Red Hat OpenShift.

      2. Select the Installed Namespace for the operator.

        The default operator namespace is cert-manager-operator; if that namespace doesn't exist, it is created for you.

      3. Select an Update approval strategy:
        • Automatic: allow Operator Lifecycle Manager (OLM) to automatically update the operator when a new version is available.
        • Manual: require a user with the appropriate credentials to approve all operator updates.
      4. Click Install.
    6. Verify the cert-manager installation by completing the following steps:
      1. Click to Operators > Installed Operators.

      2. Verify that cert-manager Operator for Red Hat OpenShift is listed with a Status of Succeeded in the cert-manager-operator namespace.

      3. Verify that cert-manager pods are up and running by running the following command:
        oc get pods -n cert-manager

        For a successful installation, the response looks like the following example:

        NAME                                       READY   STATUS    RESTARTS   AGE
cert-manager-bd7fbb9fc-wvbbt               1/1     Running   0          3m39s
cert-manager-cainjector-56cc5f9868-7g9z7   1/1     Running   0          4m5s
cert-manager-webhook-d4f79d7f7-9dg9w       1/1     Running   0          4m9s
  11. Create the ibm-common-services-operator subscription, if it does not already exist.
    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: v4.6
  name: ibm-common-service-operator
  source: opencloud-operators
  sourceNamespace: openshift-marketplace

      Where: <namespace> is one of the following values:

      • openshift-operators if you are installing the operator in all namespaces
      • The namespace created in step 3 if you are installing the operator in a single namespace
    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, IBM Cloud Pak foundational services, or Operand Deployment Lifecycle Manager 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 and Operand Deployment Lifecycle Manager operators to install.