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

OpenShift-only content 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).
Ensure that you have completed the steps in Adding the IBM App Connect Operator to a catalog.
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
```
Restriction: Do not install into any of these system namespaces, which might impose restrictions on assigning role-based access control (RBAC) permissions or security context constraints:
- The default namespace
- Any namespace prefixed with kube-
- The openshift namespace or any namespace prefixed with openshift-
  The exception is the openshift-operators namespace, which is used for a cluster-wide installation.

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-mongodb-operator-app                             Cloud Pak for Integration   6d6h
ibmz-mongodb-ee-operator                             Certified Operators         6d6h
ibm-events-operator                                  Cloud Pak for Integration   6d6h
ibm-appconnect                                       IBM App Connect operator    6d3h
ibm-namespace-scope-operator                         Cloud Pak for Integration   6d6h
ibm-crossplane-operator-app                          Cloud Pak for Integration   6d6h
ibm-common-service-operator                          Cloud Pak for Integration   6d6h
...

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.ppc64le=supported
              operatorframework.io/arch.s390x=supported
              operatorframework.io/os.linux=supported
              provider=IBM
              provider-url=

...
# Documentation
See the [IBM App Connect documentation](https://ibm.biz/ACEv12ContainerDocs-lts).

      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/ACEv12ContainerDocs-lts
        Name:  Dashboard documentation
        URL:   https://ibm.biz/acedashbdop-lts
        Name:  Integration Server documentation
        URL:   https://ibm.biz/createintserver-ace-lts
        Name:  Designer Authoring documentation
        URL:   https://ibm.biz/acedesignerop-lts
        Name:  SwitchServer documentation
        URL:   https://ibm.biz/aceswitchsrvop-lts
        Name:  Configuration documentation
        URL:   https://ibm.biz/aceconfig-lts
        Name:  Trace documentation
        URL:   https://ibm.biz/acetraceop-lts
      Maintainers:
        Name:            IBM
      Maturity:          stable
      Min Kube Version:  1.23.0
      Provider:
        Name:  IBM
      Related Images:
        icr.io/appc-dev/acecc-proxy@sha256:ab5acadb13b10850ed3a25646241b04e4e3d363a8c54c38adafe368836411ef0
        cp.icr.io/cp/appc/acecc-designer-runtime-prod@sha256:a0c36d8cf2e9f03caa1ce5ebe66fc0b8dc4f80bae9c29b749e16825d63f9a100
        cp.icr.io/cp/appc/acecc-dashboard-prod@sha256:ad22c484b1c849a85e638dcc67d4263e144509eaf5de3c0dc28e7fca0e540c85
...
      Version:      5.0.18
    Entries:
      Name:         ibm-appconnect.v5.0.18
      Version:      5.0.18
      Name:         ibm-appconnect.v5.0.0
      Version:      5.0.0
    Name:           v5.0-lts
  Default Channel:  v5.0-lts
  Package Name:     ibm-appconnect
  Provider:
    Name:  IBM
Events:    <none>

Create an OperatorGroup object that identifies the namespace in which role-based access control (RBAC) permissions for the IBM App Connect Operator will be generated, and where the Operator’s Cluster Service Version (CSV) will be available. To do so, you must define an OperatorGroup resource in a YAML file and then use it to create the 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 install (or subscribe) the IBM App Connect Operator must contain an OperatorGroup that matches the Operator's install mode, which can be OwnNamespace or SingleNamespace (for installation into a single namespace), or AllNamespaces (for a cluster wide installation into all namespaces). If you intend to install the Operator cluster wide, you do not need to create an OperatorGroup because the openshift-operators namespace (into which the Operator will be installed) already has an appropriate OperatorGroup in place. You can therefore skip this step.

However, if you intend to install the Operator into a single namespace that doesn't already contain an appropriate OperatorGroup for use, you must create an OperatorGroup 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
```

Add the IBM App Connect Operator to the OperatorGroup that you created in the previous step. To do so, you must define a Subscription resource in a YAML file and then use it to create a Subscription object in the namespace where the OperatorGroup was created:

From your local computer, create a file called appconn-sub.yaml with the following YAML content for your installation environment.

Online installation environment that is connected to the internet Air-gapped installation environment with no connection to the internet

Online installation environment that is connected to the internet	Air-gapped installation environment with no connection to the internet
Installing from your deployed IBM App Connect Operator catalog source: `apiVersion: operators.coreos.com/v1alpha1 kind: Subscription metadata: name: ibm-appconnect namespace: namespaceName spec: channel: v5.0-lts name: ibm-appconnect source: appconnect-operator-catalogsource sourceNamespace: openshift-marketplace` Installing from the IBM Operator Catalog: `apiVersion: operators.coreos.com/v1alpha1 kind: Subscription metadata: name: ibm-appconnect namespace: namespaceName spec: channel: v5.0-lts name: ibm-appconnect source: ibm-operator-catalog sourceNamespace: openshift-marketplace`	Installing from the internal product-specific catalog in your restricted network: `apiVersion: operators.coreos.com/v1alpha1 kind: Subscription metadata: name: ibm-appconnect namespace: namespaceName spec: channel: v5.0-lts name: ibm-appconnect source: appconnect-operator-catalogsource sourceNamespace: openshift-marketplace`

Installing from your deployed IBM App Connect Operator catalog source:

apiVersion: operators.coreos.com/v1alpha1
kind: Subscription
metadata:
  name: ibm-appconnect
  namespace: namespaceName
spec:
  channel: v5.0-lts
  name: ibm-appconnect
  source: appconnect-operator-catalogsource
  sourceNamespace: openshift-marketplace

Installing from the IBM Operator Catalog:

apiVersion: operators.coreos.com/v1alpha1
kind: Subscription
metadata:
  name: ibm-appconnect
  namespace: namespaceName
spec:
  channel: v5.0-lts
  name: ibm-appconnect
  source: ibm-operator-catalog
  sourceNamespace: openshift-marketplace

Installing from the internal product-specific catalog in your restricted network:

apiVersion: operators.coreos.com/v1alpha1
kind: Subscription
metadata:
  name: ibm-appconnect
  namespace: namespaceName
spec:
  channel: v5.0-lts
  name: ibm-appconnect
  source: appconnect-operator-catalogsource
  sourceNamespace: openshift-marketplace

If installing into a single namespace, replace namespaceName with your preferred namespace. If installing cluster wide, replace namespaceName with openshift-operators.
The spec.channel: v5.0-lts 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 with a value of Manual to the supplied YAML code, as shown in the following example. (Do not use this Manual setting if you are installing the Operator from a product-specific App Connect catalog source. The use of a product-specific catalog source enables you to control which upgrades to apply because upgrades happen only when the image digest for the catalog source is changed.)
```
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.

To install the Operator, create the Subscription object:
```
oc apply -f appconn-sub.yaml
```

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.
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.21   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 Operator. 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.21
  - ibm-appconnect.v5.0.18
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 Operator. 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 Operator have been installed:

oc get csv -n namespaceName

You should see output similar to this. The REPLACES column might be blank if the installed Operator is the first release in the associated channel.

NAME                                   DISPLAY                               VERSION     REPLACES                              PHASE
ibm-appconnect.v5.0.18                 IBM App Connect                       5.0.18                                            Succeeded
ibm-common-service-operator.v3.19.21   IBM Cloud Pak foundational services   3.19.21     ibm-common-service-operator.v3.19.20  Succeeded

What to do next

Deploy License Service to track license consumption of IBM App Connect.
For compliance with the licensing requirements, ensure that License Service is deployed on your cluster to monitor and measure license usage of App Connect. For more information, see Tracking license consumption of IBM App Connect.
Obtain an entitlement key and create your IBM App Connect authoring and runtime environments, and other resources.
After you install the Operator, users with the relevant permissions can use the provided APIs to create instances of the App Connect components. If you do not already have one, an entitlement key (supplied as a Kubernetes pull secret) is required to pull the software images for these components from the IBM Entitled Registry. For more information, see Obtaining and applying your IBM Entitled Registry entitlement key and Creating your authoring and runtime environments, and other IBM App Connect resources.
Optionally enable monitoring.
If you want to enable users to query metrics for their deployed instances from the OpenShift monitoring dashboard, you must additionally request the Monitoring service that is provided with IBM Cloud Pak foundational services and then enable monitoring for user-defined projects (namespaces). For more information, see Requesting the Monitoring service from IBM Cloud Pak foundational services.