Installing the IBM MQ Operator

The IBM® MQ Operator can be installed onto Red Hat® OpenShift® using the OpenShift console or command line interface (CLI).

Before you begin

To ensure that your installation goes as smoothly as possible, make sure that you understand all of the prerequisites and requirements before you start your installation. See Planning for IBM MQ in containers.

Important: Review the guidance on structuring your deployment before you install the IBM MQ Operator.

About this task

The following steps represent the typical task flow for installing your IBM MQ Operator:

Install Red Hat OpenShift Container Platform.
Configure storage.
Mirror images (air-gap only).
Add the IBM operator catalog and prepare your cluster.
Install the IBM MQ Operator.
Create the entitlement key secret (online installs only).
Optional: Install IBM Cloud Pak® for Integration (CP4I) and its dependencies.
Deploy the License Service.
Deploy a queue manager.

Procedure

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 2.0 or later, you must install OpenShift Container Platform 4.12 or later. Also note that only the OpenShift Container Platform Extended Update Support (EUS) releases are supported, which are the even-numbered minor releases, for example 4.14 and 4.16. 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.
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 Storage considerations for 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 on the CP4I Storage considerations page.
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. Use the following values:
```
export OPERATOR_PACKAGE_NAME=ibm-mq
export OPERATOR_VERSION=3.1.1
```
- 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 IBM MQ 9.3.4 or later.
  - You are using a CP4I 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 the previous statements are true, then SSO is provided by Keycloak and you must mirror each of the following components:
  - Certificate manager
  - 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.
Add the IBM MQ Operator catalog source.

Add the catalog source that makes the operators available to your cluster. See Adding the IBM MQ Operator catalog source.
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.
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.
Optional: Install CP4I 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 IBM MQ 9.3.4 or later.
- You are using a CP4I license.
- The IBM MQ Console is enabled.
- You are using the CP4I 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 cert-manager Operator for the Red Hat OpenShift Container Platform.
- Install the IBM Cloud Pak foundational services operator in the same installation mode as the CP4I Operator. For supported versions, see Operator channel versions for this release
- Install the CP4I 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.
Deploy the License Service.

This is required for monitoring license usage of queue managers. Follow the instructions in Deploying License Service.
Deploy a queue manager.
For instructions on deploying an example quick start queue manager, see Deploying a queue manager onto a Red Hat OpenShift Container Platform cluster.