[OpenShift Container Platform][IBM Cloud Pak for Integration][Linux]

Installing IBM MQ Operator 2.x in an air-gap environment

This tutorial guides you in installing IBM® MQ Operator 2.x into a Red Hat® OpenShift® cluster that has no internet connectivity. You can install IBM MQ Operator in an air-gap environment using a portable storage device, or using a bastion machine.

Before you begin

These instructions are for installing the 2.x version of the IBM MQ Operator in an air-gap environment. To install IBM MQ Operator 3.0.0 and later, see Installing the IBM MQ Operator, paying particular attention to the air-gap specific steps.

Installing the IBM MQ Operator in an air-gap environment using a portable storage device

For the steps to complete the installation, see Mirroring images with a portable storage device in the IBM Cloud Pak® for Integration documentation. If you are installing only IBM MQ, then replace all occurrences of the following environment variables with the values given here:
export CASE_NAME=ibm-mq
export CASE_ARCHIVE_VERSION=version_number
export CASE_INVENTORY_SETUP=ibmMQOperator
where version_number is the version of the case that you want to use to do the air-gap install. For a list of available case versions, see https://github.com/IBM/cloud-pak/tree/master/repo/case/ibm-mq. Review Version support for the IBM MQ Operator to determine which operator channel to choose.

Installing the IBM MQ Operator in an air-gap environment using a bastion machine

  1. Prerequisites
  2. Prepare a Docker registry
  3. Prepare a bastion host
  4. Create environment variables for the installer and image inventory
  5. Download the IBM MQ installer and image inventory
  6. Log in to the OpenShift Container Platform cluster as a cluster administrator
  7. Create a Kubernetes namespace for the IBM MQ Operator
  8. Mirror the images and configure the cluster
  9. Install the IBM MQ Operator.
  10. Deploy IBM MQ Queue Manager

Prerequisites

  1. A OpenShift Container Platform cluster must be installed. For the supported OpenShift Container Platform versions, see Version support for the IBM MQ Operator.
  2. A Docker registry must be available. For more information, see Prepare a Docker registry.
  3. A bastion server must be configured. For more information, see Prepare a bastion host.

Prepare a Docker registry

A local Docker registry is used to store all images in your local environment. You must create such a registry and must ensure that it meets the following requirements:

  • Supports Docker Manifest V2, Schema 2.
  • Supports multi-architecture images.
  • Is accessible from both the bastion server and your OpenShift Container Platform cluster nodes.
  • Has the username and password of a user who can write to the target registry from the bastion host.
  • Has the username and password of a user who can read from the target registry that is on the Red Hat OpenShift cluster nodes.
  • Allows path separators in the image name.

After you create the Docker registry, you must configure the registry:

  • An example of a simple registry is included in Creating a mirror registry for installation in a restricted network in the Red Hat OpenShift documentation.
  • Verify that each namespace meets the following requirements:
    • Supports auto-repository creation.
    • Has credentials of a user who can write and create repositories. The bastion host uses these credentials.
    • Has credentials of a user who can read all repositories. The OpenShift Container Platform cluster uses these credentials.

Prepare a bastion host

Prepare a bastion host that can access the OpenShift Container Platform cluster, the local Docker registry, and the Internet. The bastion host must be on a Linux® for x86-64 platform with any operating system that the IBM Cloud Pak CLI and the OpenShift Container Platform CLI support.

Complete these steps on your bastion node:

  1. Install OpenSSL version 1.11.1 or higher.
  2. Install Docker or Podman on the bastion node.
  3. Install skopeo version 1.x.x on the bastion node. To install skopeo, run these commands:
    yum check-update
yum install skopeo
  4. Install the IBM Cloud Pak CLI. Install the latest version of the binary file for your platform. For more information, see cloud-pak-cli.
    1. Download the binary file.
      wget https://github.com/IBM/cloud-pak-cli/releases/download/vversion-number/binary-file-name
      For example:
      wget https://github.com/IBM/cloud-pak-cli/releases/latest/download/cloudctl-linux-amd64.tar.gz
    2. Extract the binary file.
      tar -xf binary-file-name
    3. Run the following commands to modify and move the file
      chmod 755 file-name
mv file-name /usr/local/bin/cloudctl
    4. Confirm that cloudctl is installed:
      cloudctl --help
  5. Install the oc OpenShift Container Platform CLI tool.

    For more information, see OpenShift Container Platform CLI tools

  6. Create a directory that serves as the offline store.

    The following is an example directory. This example is used in the subsequent steps.

    mkdir $HOME/offline

    Note: This offline store must be persistent to avoid transferring data more than once. The persistence also helps to run the mirroring process multiple times or on a schedule.

Create environment variables for the installer and image inventory

Create the following environment variables with the installer image name and the image inventory:
export CASE_ARCHIVE_VERSION=version_number
export CASE_ARCHIVE=ibm-mq-$CASE_ARCHIVE_VERSION.tgz
export CASE_INVENTORY=ibmMQOperator
where version_number is the version of the case that you want to use to do the airgap install. For a list of available case versions, see https://github.com/IBM/cloud-pak/tree/master/repo/case/ibm-mq. Review Version support for the IBM MQ Operator to determine which operator channel to choose.

Download the IBM MQ installer and image inventory

Download the ibm-mq installer and image inventory to the bastion host: 
cloudctl case save \
    --case https://github.com/IBM/cloud-pak/raw/master/repo/case/ibm-mq/$CASE_ARCHIVE_VERSION/$CASE_ARCHIVE \
    --outputdir $HOME/offline/

Log in to the OpenShift Container Platform cluster as a cluster administrator

The following is an example command to log in to the OpenShift Container Platform cluster: 
oc login cluster_host:port --username=cluster_admin_user --password=cluster_admin_password

Create a Kubernetes namespace for the IBM MQ Operator

Create an environment variable with a namespace to install the IBM MQ Operator, then create the namespace:

export NAMESPACE=ibm-mq-test
oc create namespace ${NAMESPACE}

Mirror the images and configure the cluster

Complete these steps to mirror the images and configure your cluster:
Note: Do not use the tilde within double quotation marks in any command. For example, do not use args "--registry registry --user registry_userid --pass registry_password --inputDir ~/offline". The tilde does not expand and your commands might fail.
  1. Store authentication credentials for all source Docker registries.

    All IBM Cloud® Platform Common Services, IBM MQ Operator image and IBM MQ Advanced Developer image are stored in public registries that do not require authentication. However, IBM MQ Advanced Server (non-Developer), other products and third-party components require one or more authenticated registries. The following registries require authentication:

    • cp.icr.io
    • registry.redhat.io
    • registry.access.redhat.com

    For more information about these registries, see Create registry namespaces.

    You must run the following command to configure credentials for all registries that require authentication. Run the command separately for each such registry:

    cloudctl case launch \
--case $HOME/offline/${CASE_ARCHIVE} \
--inventory ${CASE_INVENTORY} \
--action configure-creds-airgap \
--namespace ${NAMESPACE} \
--args "--registry registry --user registry_userid --pass registry_password --inputDir $HOME/offline"

    The command stores and caches the registry credentials in a file on your file system in the $HOME/.airgap/secrets location.

  2. Create environment variables with the local Docker registry connection information.
    export LOCAL_DOCKER_REGISTRY=IP_or_FQDN_of_local_docker_registry
export LOCAL_DOCKER_USER=username
export LOCAL_DOCKER_PASSWORD=password
    Note: The Docker registry uses standard ports such as 80 or 443. If your Docker registry uses a non-standard port, specify the port by using the syntax host:port. For example: 
    export LOCAL_DOCKER_REGISTRY=myregistry.local:5000
  3. Configure an authentication secret for the local Docker registry.

    Note: This step needs to be done only one time.

    cloudctl case launch \
--case $HOME/offline/${CASE_ARCHIVE} \
--inventory ${CASE_INVENTORY} \
--action configure-creds-airgap \
--namespace ${NAMESPACE} \
--args "--registry ${LOCAL_DOCKER_REGISTRY} --user ${LOCAL_DOCKER_USER} --pass ${LOCAL_DOCKER_PASSWORD}"

    The command stores and caches the registry credentials in a file on your file system in the $HOME/.airgap/secrets location.

  4. Configure a global image pull secret and ImageContentSourcePolicy.
    1. Check whether a node restart is required.
      • In OpenShift Container Platform version 4.4 and above, and on a new installation of IBM MQ Operator using airgap, this step restarts all cluster nodes. The cluster resources might be unavailable until the time the new pull secret is applied.
      • In IBM MQ Operator 1.8, the CASE is updated to include an additional mirroring source for images. Therefore when you upgrade from previous versions of IBM MQ Operator to version 1.8 or above, a node restart is triggered.
      • To check if this step needs a node restart, add the --dry-run option to the code for this step. This generates the latest ImageContentSourcePolicy and displays it in the console window(stdout). If this ImageContentSourcePolicy differs from the cluster configured ImageContentSourcePolicy, a restart occurs. 
        cloudctl case launch \
--case $HOME/offline/${CASE_ARCHIVE} \
--inventory ${CASE_INVENTORY} \
--action configure-cluster-airgap \
--namespace ${NAMESPACE} \
--args "--registry ${LOCAL_DOCKER_REGISTRY} --user ${LOCAL_DOCKER_USER} --pass ${LOCAL_DOCKER_PASSWORD} --inputDir $HOME/offline --dryRun"
    2. To configure the global image pull secret and ImageContentSourcePolicy, run the code for this step without the --dry-run option:
      cloudctl case launch \
--case $HOME/offline/${CASE_ARCHIVE} \
--inventory ${CASE_INVENTORY} \
--action configure-cluster-airgap \
--namespace ${NAMESPACE} \
--args "--registry ${LOCAL_DOCKER_REGISTRY} --user ${LOCAL_DOCKER_USER} --pass ${LOCAL_DOCKER_PASSWORD} --inputDir $HOME/offline"
  5. Verify that the ImageContentSourcePolicy resource is created.
    oc get imageContentSourcePolicy
  6. Optional: If you are using an insecure registry, you must add the local registry to the cluster insecureRegistries list.
    oc patch image.config.openshift.io/cluster --type=merge -p '{"spec":{"registrySources":{"insecureRegistries":["'${LOCAL_DOCKER_REGISTRY}'"]}}}'
  7. Verify your cluster node status.
    oc get nodes

    After the imageContentsourcePolicy and global image pull secret are applied, you might see the node status as Ready, Scheduling, or Disabled. Wait until all the nodes show a Ready status.

  8. Mirror the images to the local registry.
    cloudctl case launch \
--case $HOME/offline/${CASE_ARCHIVE} \
--inventory ${CASE_INVENTORY} \
--action mirror-images \
--namespace ${NAMESPACE} \
--args "--registry ${LOCAL_DOCKER_REGISTRY} --user ${LOCAL_DOCKER_USER} --pass ${LOCAL_DOCKER_PASSWORD} --inputDir $HOME/offline"

Install the IBM MQ Operator.

  1. Log in to your Red Hat OpenShift cluster web console.
  2. Create a catalog source. Use the same terminal that executed the previous steps.
    cloudctl case launch \
--case $HOME/offline/${CASE_ARCHIVE} \
--inventory ${CASE_INVENTORY} \
--action install-catalog \
--namespace ${NAMESPACE} \
--args "--registry ${LOCAL_DOCKER_REGISTRY} --recursive"
  3. Verify that the CatalogSource is created for the Common Services Installer Operator.
    oc get pods -n openshift-marketplace
oc get catalogsource -n openshift-marketplace
  4. Install the IBM MQ Operator using OLM.
    1. From the navigation pane, click Operators > OperatorHub.

      The OperatorHub page is displayed.

    2. In the All Items field, enter IBM MQ.

      The IBM MQ catalog entry is displayed.

    3. Select IBM MQ.

      The IBM MQ window is displayed.

    4. Click Install.

      The Create Operator Subscription page is displayed.

    5. Review Version support for the IBM MQ Operator to determine which operator channel to choose.
    6. Set Installation Mode to either the specific namespace that you created, or the cluster wide scope.
    7. Click Subscribe.

      IBM MQ is added to the Installed Operators page.

    8. Check the status of the operator on the Installed Operators page. The status changes to Succeeded when the installation is complete.

Deploy IBM MQ Queue Manager

To create a new queue manager under the installed operator, see Deploying a queue manager onto a Red Hat OpenShift Container Platform cluster.