Installing the IBM MQ Operator for use with IBM Cloud Pak for Integration on Red Hat OpenShift

For use with the IBM Cloud Pak® for Integration, the IBM® MQ Operator can be installed onto Red Hat® OpenShift® through the OpenShift console or command line interface (CLI).

1. Install Red Hat OpenShift Container Platform.
   For detailed steps to install OpenShift, see Installing Red Hat software 4.6 or later.

   Important: Ensure that you install a supported version of OpenShift Container Platform. For example, to use IBM MQ Operator 3.9 or later, you must install OpenShift Container Platform 4.12 or later. For more information, see IBM Cloud Pak and Red Hat OpenShift Container Platform compatibility.

   For any steps that use the Red Hat OpenShift Container Platform CLI, you must be logged in to your OpenShift cluster with oc login. To install the CLI, see Getting started with the OpenShift CLI.

   After you install OpenShift, you can verify and gain access to your container software by using the IBM entitlement key that you create in Create the entitlement key secret.

2. Configure storage.

   You must define storage classes in Red Hat OpenShift Container Platform and set your storage configuration to satisfy your sizing requirements.

   Important: IBM MQ single-instance and Native HA queue managers can use RWO access mode, while multi-instance queue managers require RWX as described in Planning storage for the IBM MQ Operator. IBM MQ multi-instance queue managers require particular file system characteristics, which can be verified using the instructions for Testing a shared file system for IBM MQ.

   A list of known compliant and non-compliant file systems, and notes on other limits or restrictions, can be found in the Testing statement for IBM MQ file systems.

   Recommended storage providers can be found in Storage considerations in the IBM Cloud Pak for Integration documentation.

3. Mirror images (air-gap only).

   If your cluster is in a restricted (air-gapped) network environment, you must mirror the IBM MQ images. Depending on your configuration, you might also need to mirror some additional components. Read the following information, then mirror the images as required.

   • You must mirror the IBM MQ images.
     Important: From version 3.5.0 the IBM MQ CASE has changed, now containing only a single queue manager version. The image mirroring process runs considerably faster, but might need to be run multiple times; once for each version of the queue manager that is being installed.

     For more information, see IBM MQ CASE for air-gap install and upgrade.

     You must look up which IBM MQ CASE versions contain the operator and queue manager versions you require, and repeat the air-gap mirror process for each. See the IBM MQ CASE Lookup Tables for the version mappings.

     For example, when following the instructions linked below to mirror images, you install the latest operator and single corresponding queue manager version by using the following values:

     export OPERATOR_PACKAGE_NAME=ibm-mq
     export OPERATOR_VERSION=3.9.1

     For information about the contents of the IBM MQ CASE, which is used for air-gap installs and upgrades, see IBM MQ CASE for air-gap install and upgrade.

   • You must also mirror some additional required components if you intend to deploy at least one queue manager where all of the following statements are true:
     • You are using a IBM Cloud Pak for Integration license.
     • The IBM MQ Console is enabled.
     • You are using the IBM Cloud Pak for Integration Keycloak service for IBM MQ Console single sign-on (SSO) authentication and authorization (the default).
     If all of the previous statements are true, then SSO is provided by Keycloak. Therefore, as well as for the IBM MQ Operator, you must also repeat the steps for each of these additional required components:
     • IBM Cloud Pak foundational services
     • IBM Cloud Pak for Integration
     • Keycloak (Red Hat OpenShift operator)

   To create mirror images, see Mirroring images for an air-gapped cluster.

4. Add the IBM MQ Operator catalog source.
   Add the catalog source that makes the IBM MQ Operator available to your cluster using the following values:

   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.9.1. The current SC2 version is 3.2.23.

   There are some additional required components when you deploy at least one queue manager where all of the following statements are true:

   • You are using a IBM Cloud Pak for Integration license.
   • The IBM MQ Console is enabled.
   • You are using the IBM Cloud Pak for Integration Keycloak service for IBM MQ Console single sign-on (SSO) authentication and authorization (the default).

   If all of the previous statements are true, then SSO is provided by Keycloak. Therefore, as well as for the IBM MQ Operator catalog source, you must also repeat the steps for each of these additional required components:

   • IBM Cloud Pak foundational services
   • IBM Cloud Pak for Integration
   • Keycloak (Red Hat OpenShift operator)

   Follow the steps for your required catalog sources in Adding catalog sources to a cluster.

5. Install the IBM MQ Operator.

   Choose one of the following two options (use the console, or use the CLI):

   • Option 1: Install the IBM MQ Operator using the OpenShift console.
   • Option 2: Install the IBM MQ Operator using the OpenShift CLI.
6. Create the entitlement key secret (online installs only).

   The IBM MQ Operator deploys queue manager images that are pulled from a container registry that performs a license entitlement check. This check requires an entitlement key that is stored in a docker-registry pull secret. If you do not yet have an entitlement key in the namespace in which you will install queue managers, follow these instructions to get an entitlement key and create a pull secret.

   Note: The entitlement key is not required if only IBM MQ Advanced for Developers (Non-Warranted) queue managers are going to be deployed.

   You can create the entitlement key secret using either the OpenShift console or the CLI. The following example uses the CLI:

   1. Get the entitlement key that is assigned to your IBM ID. Log in to MyIBM Container Software Library with the IBM ID and password that are associated with the entitled software.
   2. In the Entitlement keys section, select Copy key to copy the entitlement key to the clipboard.
   3. From the OpenShift CLI, run the following command to create an image pull secret called ibm-entitlement-key.

      oc create secret docker-registry ibm-entitlement-key \
      --docker-server=cp.icr.io \
      --docker-username=cp \
      --docker-password=entitlement_key \
      --docker-email=user_email 
      \--namespace=namespace

      Where entitlement_key is the entitlement key that you copied in step b, user_email> is the IBM ID associated with the entitled software, and namespace is the namespace that you installed your IBM MQ Operator into.
7. Optional: Install IBM Cloud Pak for Integration and its dependencies.
   There are some additional required components when you deploy at least one queue manager where all of the following statements are true:

   • You are using a IBM Cloud Pak for Integration license.
   • The IBM MQ Console is enabled.
   • You are using the IBM Cloud Pak for Integration Keycloak service for IBM MQ Console single sign-on (SSO) authentication and authorization (the default).

   If all the previous statements are true, then SSO is provided by Keycloak and you must complete the following additional steps:

   • Install the IBM Cloud Pak foundational services operator in the same installation mode as the IBM Cloud Pak for Integration Operator. For supported versions, see Operator channel versions for this release.
   • Install the IBM Cloud Pak for Integration Operator.
   • Optional: Deploy the Platform UI.
     1. Create the ibm-common-services namespace. When logged into your OpenShift cluster through the CLI, run the following command:

        oc new-project ibm-common-services

     2. Deploy the Platform UI.
8. Deploy the License Service.

   This is required for monitoring license usage of queue managers. Follow the instructions in Deploying License Service.

9. Deploy a queue manager.
   For instructions on deploying an example quick start queue manager, see Deploying a simple queue manager using the IBM MQ Operator on Red Hat OpenShift.