Installing the IBM MQ Operator in an airgap environment by using a bastion

This tutorial guides you in installing IBM MQ Operator into an OpenShift cluster that has no internet connectivity.

  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. An 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. We 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 the 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 OpenShift cluster nodes.
  • Allows path separators in the image name.

After creating the Docker registry, we must configure the registry:

  1. Create registry namespaces

    • ibmcom - Namespace to store all images from the dockerhub.io/ibmcom namespace.

      The ibmcom namespace is for all IBM images that are publicly available and do not require credentials to pull.

    • cp - Namespace to store the IBM images from the cp.icr.io/cp repository.

      The cp namespace is for the images in the IBM Entitled Registry that require a product entitlement key and credentials to pull. To get your entitlement key, log in to MyIBM Container Software Library with the IBM ID and password that are associated with the entitled software. In the Entitlement keys section, select Copy key to copy the entitlement key to the clipboard, then save it for use in the following steps.

    • opencloudio - Namespace to store the images from quay.io/opencloudio.

      The opencloudio namespace is for select IBM open source component images that are available on quay.io. The IBM Cloud Platform Common Services images are hosted on opencloudio.

  2. 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 the IBM Cloud Pak CLI. Install the latest version of the binary file for the 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

  4. Install the oc OpenShift Container Platform CLI tool.

    For more information, see OpenShift Container Platform CLI tools

  5. 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=1.0.0
export CASE_ARCHIVE=ibm-mq-$CASE_ARCHIVE_VERSION.tgz
export CASE_INVENTORY=ibmMQOperator


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 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 the 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.

    We 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.
    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"

    Note: In OpenShift Container Platform version 4.4, this step restarts all cluster nodes. The cluster resources might be unavailable until the time the new pull secret is applied.

  5. Verify that the ImageContentSourcePolicy resource is created.
    oc get imageContentSourcePolicy
  6. Optional: If we are using an insecure registry, we 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 the 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 the OpenShift cluster web console.
  2. Add the IBM Cloud Platform Common Services Operators to the list of installable operators.

    • Click the plus icon. The Import YAML dialog box is displayed.
    • Paste the following resource definition in the dialog box. 
      apiVersion: operators.coreos.com/v1alpha1
kind: CatalogSource
metadata:
  name: opencloud-operators
  namespace: openshift-marketplace
spec:
  displayName: IBMCS Operators
  publisher: IBM
  sourceType: grpc
  image: docker.io/ibmcom/ibm-common-service-catalog:latest
  updateStrategy:
    registryPoll:
      interval: 45m
    • Click Create.

  3. 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}"
  4. Verify that the CatalogSource is created for the Common Services Installer Operator.
    oc get pods -n openshift-marketplace
oc get catalogsource -n openshift-marketplace
  5. 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. Set Installation Mode to either the specific namespace that you created, or the cluster wide scope.
    6. Click Subscribe.

      IBM MQ is added to the Installed Operators page.

    7. 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 IBM MQ certified containers using the IBM MQ Operator.

Parent topic: Install and uninstall the IBM MQ Operator on OpenShift