Adding the IBM MQ Operator catalog source

Add the IBM® MQ Operator catalog source to your OpenShift® cluster to make the IBM MQ Operator available for installation. This task is also required if you are applying catalog source fix packs before completing an upgrade.

About this task

An Operator Catalog is an index of operators available to extend the API of a Red Hat® OpenShift Container Platform cluster to enable IBM software products.

The following catalog sources are available:

Option 1: Specific catalog source for the IBM MQ Operator.: By using a specific IBM MQ Operator catalog source, you gain full control of software versioning on a cluster and when upgrades happen. A new IBM MQ Operator version becomes available in an OpenShift cluster only after you update the catalog source. This process effectively gives you manual control of upgrades, so you do not need to use the Manual option for the Update approval setting for operators. The Manual option forces all possible upgrades to be done at the same time and can block upgrades, so use the Automatic option only. For more information, see the "Restricting automatic updates with an approval strategy" section of Installing the operators by using the Red Hat OpenShift console.; Choose this option if you are completing an upgrade and need to add the IBM MQ Operator catalog source of a newer version.; To use this option, skip to Option 1: Add specific catalog sources for the IBM MQ Operator.
Option 2: IBM Operator Catalog.: With this option, new operator versions become available and are applied without any intervention from you. So use this option only for online installations where you want automatic upgrades of the IBM MQ Operator, and where deterministic installations are not needed.; Note: This option can be useful for proof-of-concept environments but it is not suitable for production environments.; To use this option, skip to Option 2: Add the IBM Operator Catalog.

Procedure

Option 1: Add specific catalog sources for the IBM MQ Operator.

This task assumes that you have completed the first 3 steps of Installing the IBM MQ Operator.

This task must be performed by a cluster administrator and must be performed using the CLI.
1. Upgrade only: If you are applying catalog source fix packs before an upgrade, complete the following steps:
  - Confirm that your operators are running properly.
  - If there are any pending IBM MQ Operator updates that require manual approval, approve those before starting this procedure. For more information, see "Restricting automatic updates with an approval strategy" in Installing the operators by using the Red Hat OpenShift console.
2. If you have not already installed it, or if it needs updating, download the IBM Catalog Management plug-in (version 1.6.0 or later) from GitHub.
  
  This plug-in allows you to run oc ibm-pak commands against the cluster.
3. Log into your cluster by using the oc login command and your user credentials:
```
oc login openshift_url -u username -p password -n namespace
```
4. Export the following environment variables for the IBM MQ Operator:
```
export OPERATOR_PACKAGE_NAME=ibm-mq
export OPERATOR_VERSION=CHOSEN_OPERATOR_VERSION
export ARCH=ARCHITECTURE
```
  where
  - ARCHITECTURE is the architecture of the system on which you are deploying the IBM MQ Operator, and has a value of amd64, ppc64le, or s390x.
  - CHOSEN_OPERATOR_VERSION is your required version of the IBM MQ Operator. The current CD version is 3.8.1. The current SC2 version is 3.2.21.
  Important: If you are moving from the IBM Operator Catalog to the specific catalog source for the IBM MQ Operator, set OPERATOR_VERSION to the version of your deployment of the IBM MQ Operator.
5. Download the files for the IBM MQ Operator.
  Note: If you are completing an air-gapped installation, you should already have the files that you need after completing the "Mirror images" step of "Installing the IBM MQ Operator", in which case you can skip to step 8 "Apply the IBM MQ Operator catalog source to the cluster".
```
oc ibm-pak get ${OPERATOR_PACKAGE_NAME} --version ${OPERATOR_VERSION}
```
6. Generate the catalog source required for the IBM MQ Operator:
```
oc ibm-pak generate mirror-manifests ${OPERATOR_PACKAGE_NAME} icr.io --version ${OPERATOR_VERSION}
```
7. Optional: Generate the catalog sources and save them on another directory.
  1. Get the catalog source:
```
cat ~/.ibm-pak/data/mirror/${OPERATOR_PACKAGE_NAME}/${OPERATOR_VERSION}/catalog-sources.yaml
```
  2. (Optional) Navigate to the directory in your file browser to copy these artifacts into files that you can keep for re-use or for pipelines.
8. Apply the IBM MQ Operator catalog source to the cluster.
```
oc apply -f ~/.ibm-pak/data/mirror/${OPERATOR_PACKAGE_NAME}/${OPERATOR_VERSION}/catalog-sources.yaml
```
9. Confirm that the IBM MQ Operator catalog source was created in the openshift-marketplace namespace:
```
oc get catalogsource -n openshift-marketplace
```
  Example output:
```
oc get catalogsource -n openshift-marketplace   

NAME                           DISPLAY                TYPE   PUBLISHER   AGE
ibmmq-operator-catalogsource   ibm-mq-3.1.3           grpc   IBM         23h
```
You are now ready to complete Step 5 of Installing the IBM MQ Operator.
Option 2: Add the IBM Operator Catalog.
Important: Use the IBM Operator Catalog only for online installations where you want automatic upgrades of the IBM MQ Operator, and where deterministic installations are not needed. This option can be useful for proof-of-concept environments but it is not suitable for production environments.

The IBM Operator Catalog is an index of operators available to extend the API of a Red Hat OpenShift Container Platform cluster to enable IBM software products. Adding the catalog sources to your OpenShift cluster adds the IBM operators to the list of operators you can install.

This task assumes that you have completed the first 3 steps of Installing the IBM MQ Operator.

This task can be performed by using the CLI or by using the OpenShift web console.
Using the CLI
1. Copy the following resource definition for IBM operators into a local file on your computer:
```
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:latest
  updateStrategy:
    registryPoll:
      interval: 45m
```
2. Run the following command. Replace filename.yaml with the name of the file you created in the previous step:
```
oc apply -f filename.yaml
```
Using the OpenShift web console
1. Log into the OpenShift web console with your OpenShift cluster administrator credentials.
2. In the banner, click the plus ("+") icon to open the Import YAML dialog box.
  Note: You do not need to select a value for Project. The YAML code in the next step already includes the correct value for metadata:namespace, which ensures that the catalog source is installed in the correct project (namespace).
3. 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
  image: 'icr.io/cpopen/ibm-operator-catalog:latest'
  publisher: IBM
  sourceType: grpc
  updateStrategy:
    registryPoll:
      interval: 45m
```
4. Click Create.
You are now ready to complete Step 5 of Installing the IBM MQ Operator.