Installing operators
Install operators for API Connect, DataPower, and common services so that you can deploy the API Connect subsystems.
Before you begin
The API Connect operator and operand must be from the same release and fix pack level. Table 1 lists the current version of the operator and operand for API Connect.
API Connect (operand) | Operator channel version | Highest operator version |
---|---|---|
10.0.1.12-eus | v2.1.11-eus | 2.1.15 |
The version of the gateway subsystem must either match the API Connect version, or be one release
older. The gateway subsystem version cannot be newer than the API Connect subsystem version. If API
Connect is on version n,
only DataPower Gateway versions n
or
n-1
are supported. DataPower Gateway version n+1
is not
supported.
Procedure
- Obtain an entitlement key for the Entitled Registry:
- Log in to the IBM Container Library.
- In the Container software library, select Get entitlement key.
- After the Access your container software heading, click Copy key.
- Copy the key to a safe location.
-
Create a global pull secret:
- Open the OpenShift web console, click Workloads > Secrets.
- Select the project
openshift-config
. - Select
pull-secret
from the secret list. - Select Actions > Edit Secret > Add Credentials.
- Set Registry Server Address to
cp.icr.io
. - Set username to
cp
. - Set Password to the entitlement key generated in Step 1.
- Click Save. Note: On OpenShift v4.6 the cluster nodes will restart as part of this step.
- Add the IBM Common Services Catalog source:
- Open the OpenShift web console, and click + (in the page banner) to open the Import YAML dialog box.
- 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
- Click Create.
-
Add the IBM Operator Catalog source:
- In the OpenShift web console, and click + (in the page banner) to open the Import YAML dialog box.
- 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
- Click Create.
-
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.
- OpenShift restricts the use of default namespaces for installing non-cluster services. The
following namespaces cannot be used to install API Connect:
-
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.- 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>
- Apply the OperatorGroup object with the following command:
oc apply -f apiconnect-operator-group.yaml
- 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:
-
Create the
apiconnect
subscription.- 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.11-eus installPlanApproval: Manual name: ibm-apiconnect source: ibm-operator-catalog sourceNamespace: openshift-marketplace
Warning: Do not setinstallPlanApproval: 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 toManual
a notice displays that a new version is available and gives the option to upgrade. - 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:- Click 'Upgrade available'.
- Click 'Preview InstallPlan'.
- Click 'Approve'.
Wait for
IBM API Connect
,IBM DataPower Gateway
, andIBM Common Service Operator
operators to install. TheIBM 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:- Uninstall the DataPower operator deployment:
- In the OpenShift Form UI, click Operators > Installed Operators.
- Type
datapower
in the Filter by name field (or scroll until you locate the operator). - Select the operator and click Actions > Uninstall Operator.
- 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
- Install the newer DataPower operator by running the following
command:
oc apply -f ibm-datapower.yaml
- Create the