Installing the IBM App Connect Operator from the Red Hat OpenShift CLI

Use these instructions to install the IBM® App Connect Operator by using the Red Hat® OpenShift CLI.

Before you begin

Ensure that you have cluster administrator authority with cluster-admin permissions.
Ensure that cluster logging is deployed in your cluster (if you require persistent logging).
Decide how to control upgrades to the Operator when new versions become available. The approval strategy that you specify while installing will determine how the Operator is upgraded after installation. To help you choose a suitable approval strategy for your environment, review the Upgrade considerations for channels, versions, and licenses before you start this task.

Procedure

To install and subscribe to the IBM App Connect Operator, complete the following steps:

From the command line, log in to your OpenShift cluster by using the oc login command.
If you want to install the IBM App Connect Operator into an existing namespace or cluster wide, go to step 3. Otherwise, create a namespace to use for the IBM App Connect Operator by running this command, where namespaceName represents the namespace (project) name that you want to create.
```
oc new-project namespaceName
```

View the list of Operators that are available to the cluster from the OperatorHub:

oc get packagemanifests -n openshift-marketplace

Tip: Optionally append | grep ibm as a filter.

You should see the IBM App Connect Operator CatalogSource in this list; for example:

...
ibm-common-service-operator                          IBMCS Operators                            55d
ibm-spectrum-scale-csi-operator                      Community Operators                        55d
ibm-licensing-operator-app                           IBMCS Operators                            55d
ibm-integration-asset-repository                     IBM Asset Repo Operator Catalog            53d
ibm-zen-operator                                     IBMCS Operators                            55d
ibm-appconnect                                       IBM App Connect operator                   55d
ibm-block-csi-operator                               Certified Operators                        55d
...

Inspect the IBM App Connect Operator (ibm-appconnect) to verify its supported install modes and available channels:

oc describe packagemanifests ibm-appconnect -n openshift-marketplace

You should see similar details to this:

Name:         ibm-appconnect
Namespace:    openshift-marketplace
Labels:       catalog=appconnect-operator-catalogsource
              catalog-namespace=openshift-marketplace
              operatorframework.io/arch.amd64=supported
              operatorframework.io/arch.s390x=supported
              operatorframework.io/os.linux=supported
              provider=IBM
              provider-url=
...

      Display Name:  IBM App Connect
      Install Modes:
        Supported:  true
        Type:       OwnNamespace
        Supported:  true
        Type:       SingleNamespace
        Supported:  false
        Type:       MultiNamespace
        Supported:  true
        Type:       AllNamespaces
      Keywords:
        appconnect
        app connect
        app connect enterprise
        ace
        designer
        dashboard
        switch
        integration
        cloud pak
        cloud pak for integration
        cp4i
      Links:
        Name:  App Connect documentation
        URL:   https://ibm.biz/ACEv11ContainerDocs-eus
        Name:  App Connect Dashboard documentation
        URL:   http://ibm.biz/acedashbdop-eus
        Name:  App Connect Integration Server documentation
        URL:   http://ibm.biz/aceintsrvrop-eus
        Name:  App Connect Designer Authoring documentation
        URL:   http://ibm.biz/acedesignerop-eus
        Name:  App Connect SwitchServer documentation
        URL:   http://ibm.biz/aceswitchsrvop-eus
        Name:  App Connect Configuration documentation
        URL:   http://ibm.biz/aceconfig-eus
      Maintainers:
        Name:    IBM
      Maturity:  stable
      Provider:
        Name:  IBM
      Related Images:
        icr.io/cpopen/appconnect-operator@sha256:957c4f699c6e0d3c3ab174f0534e9efd4854ff7d2cbf0102c010325ad37f6be1
        icr.io/cpopen/appconnect-operator-init@sha256:58db8743ec43cd3c7ed8a4948c97e3fe3c53dfca275d5c0cf467267e75620bd6
      Version:      1.1.10
    Name:           v1.1-eus
  Default Channel:  v1.1-eus
  Package Name:     ibm-appconnect
  Provider:
    Name:  IBM
Events:    <none>

C:\WINDOWS\system32>

Create an OperatorGroup object YAML file and use it to create an OperatorGroup object. An OperatorGroup is an Operator Lifecycle Manager (OLM) resource that selects target namespaces in which to generate required RBAC access for all Operators in the same namespace as the OperatorGroup.

The namespace to which you subscribe the IBM App Connect Operator must have an OperatorGroup that matches the Operator's install mode, which can be OwnNamespace, SingleNamespace, or AllNamespaces. If you intend to use the AllNamespaces (cluster wide) mode, then the openshift-operators namespace already has an appropriate OperatorGroup in place.

However, if you intend to use the OwnNamespace or SingleNamespace mode and you do not already have an appropriate OperatorGroup in place, you must create one as follows:
1. From your local computer, create a file called appconn-operator-group.yaml with the following content. Replace operatorgroupName and namespaceName with your preferred values.
```
apiVersion: operators.coreos.com/v1
kind: OperatorGroup
metadata:
  name: operatorgroupName
  namespace: namespaceName
spec:
  targetNamespaces:
  - namespaceName
```
2. Create the OperatorGroup object:
```
oc apply -f appconn-operator-group.yaml
```
Create a Subscription object YAML file to define a subscription that will be used to keep the IBM App Connect Operator up to date:
1. From your local computer, create a file called appconn-sub.yaml with the following YAML content.
  - The spec.channel: v1.1-eus setting defines the update channel that OLM will track for new versions of the Operator.
  - By default, an Automatic approval strategy is set to allow the running instance of your Operator to be automatically upgraded whenever new versions are made available to the channel.
    If you would prefer to review a generated Install Plan for the new Operator version before manually approving this installation (or an upgrade), add a spec.installPlanApproval setting to the supplied YAML code, as shown in the following example:
    spec: installPlanApproval: Manual
    Tip: You can change the approval strategy later if required by running a command such as oc edit; for example:
    
    oc edit subscription ibm-appconnect -n namespaceName
    
    This command will automatically open the default text editor for your operating system or open another configured editor. You can then update and save the YAML definition, and close the text editor to apply the command.
  - If using the OwnNamespace or SingleNamespace install mode, replace namespaceName with your preferred namespace. If using the AllNamespaces install mode, replace namespaceName with openshift-operators.
```
apiVersion: operators.coreos.com/v1alpha1
kind: Subscription
metadata:
  name: ibm-appconnect
  namespace: namespaceName
spec:
  channel: v1.1-eus
  name: ibm-appconnect
  source: ibm-operator-catalog
  sourceNamespace: openshift-marketplace
```
2. Create the Subscription object:
```
oc apply -f appconn-sub.yaml
```
Note:
To qualify for Extended Update Support (EUS), retain the dependent Operators at the installed versions:
- Operator for Apache CouchDB: 2.0.x or later
- IBM Cloud Pak foundational services Operator 3.19.x (delivered to the v3 channel) or the previously named IBM Cloud Platform Common Services Operator 3.6.2 or later 3.6.x versions (delivered to the stable-v1 channel)
If you chose to install with a Manual approval strategy, review and approve the Install Plan of the subscription to allow OLM to install the Operator. (No additional action is needed if you selected an Automatic approval strategy.)
1. List any Install Plans, where namespaceName is the namespace that you specified for the subscription:
```
oc get installplans -n namespaceName
```
  You should see output similar to this, with the APPROVED value set to false.
```
NAME            CSV                                   APPROVAL    APPROVED
install-bl7pf   ibm-common-service-operator.v3.19.0   Manual     false
```
  In the output, the Install Plan identified in the NAME column contains details about the following cluster service versions (CSVs), which contain metadata about the IBM App Connect Operator and its dependent Operators. However, the output of the oc get installplans command might typically list only the ibm-common-service-operator CSV because this Operator is installed first.
  - ibm-common-service-operator.v3.19.0
  - ibm-appconnect.v1.1.10
  - couchdb-operator.v2.2.2
2. Display the details of the Install Plan, where installPlanName is the generated name for the Install Plan (for example, install-bl7pf):
```
oc describe installplan installPlanName -n namespaceName
```
  Review the output.
3. Approve the Install Plan for the IBM App Connect Operator and its dependent Operators. You can use commands such as oc patch or oc edit to partially update the Install Plan.
  For example, run oc patch with the following syntax (or your preferred syntax) to set spec.approved to true:
```
oc patch installplan installPlanName -n namespaceName -p '{"spec":{"approved":true}}' --type merge
```
  Or run oc edit as follows. When the text editor for your operating system opens, set spec.approved to true. Then save the YAML definition and close the text editor to apply the changes.
```
oc edit installplan installPlanName -n namespaceName
```
  OLM will now proceed with the installation.
4. Verify the approval:
```
oc get installplans -n namespaceName
```
  In the output, the APPROVED value should now be set to true.

Verify that the IBM App Connect Operator and its dependent Operators have been installed:

oc get csv -n namespaceName

You should see output similar to this:

NAME                                  DISPLAY                               VERSION   REPLACES                              PHASE
couchdb-operator.v2.2.2               Operator for Apache CouchDB           2.2.2     couchdb-operator.v2.2.1               Succeeded
ibm-appconnect.v1.1.10                IBM App Connect                       1.1.10    ibm-appconnect.v1.1.9                 Succeeded
ibm-common-service-operator.v3.19.0   IBM Cloud Pak foundational services   3.19.0    ibm-common-service-operator.v3.18.0   Succeeded

What to do next

After you install the Operator, users with the relevant permissions will be able to use the provided APIs to create instances of the App Connect components. For more information, see Creating IBM App Connect instances.