Configuring a Route to connect to a queue manager from outside a Red Hat OpenShift cluster

A set of configuration examples for connecting to a queue manager deployed in a Red Hat® OpenShift® cluster from a client application or queue manager located outside the Red Hat OpenShift cluster.

About this task

You need a Red Hat OpenShift Route to connect an application to an IBM® MQ queue manager from outside a Red Hat OpenShift cluster.

You must enable TLS on your IBM MQ queue manager and client application, because Server Name Indication (SNI) is only available in the TLS protocol when a TLS 1.2 or higher protocol is used. The Red Hat OpenShift Container Platform Router uses SNI for routing requests to the IBM MQ queue manager.

Attention: This document applies to versions 9.2.1 Continuous Delivery and later of IBM MQ clients. If your client is using version 9.2.0 Long Term Support or earlier, refer to the IBM MQ 9.1 documentation page Connecting to a queue manager deployed in a Red Hat OpenShift cluster.

[MQ 9.2.1 Dec 2020] The required configuration of the Red Hat OpenShift Route depends on the SNI behavior of your client application. IBM MQ supports two different SNI header settings depending on configuration and client type. An SNI Header is set to the hostname of the client’s destination or alternatively set to the IBM MQ channel name. For information on how IBM MQ maps a channel name to a hostname, see How IBM MQ provides multiple certificates capability.

[MQ 9.2.1 Dec 2020] Whether an SNI header is set to an IBM MQ channel name or a hostname is controlled using the OutboundSNI attribute of the SSL stanza of the client configuration file. The default is to set the SNI to an IBM MQ channel name.

Client behaviors with different OutboundSNI settings

If OutboundSNI is set to HOSTNAME, the following clients set a hostname SNI as long as a hostname is provided in the connection name:

C Clients
.NET Clients in unmanaged mode
Java/JMS Clients

If OutboundSNI is set to HOSTNAME and an IP address is used in the connection name, the following clients send a blank SNI header:

C Clients
.NET Clients in unmanaged mode
Java/JMS Clients (that cannot do a reverse DNS lookup of the hostname)

If OutboundSNI is set to CHANNEL, or not set, an IBM MQ channel name is used instead and is always sent, whether a hostname or IP address connection name is used.

The following client types do not support setting an SNI header to an IBM MQ channel name, and so always attempt to set the SNI header to a hostname regardless of the OutboundSNI setting:

AMQP clients
XR Clients
.NET Clients in managed mode (Before IBM MQ 9.2.0 Fix Pack 4 for Long Term Support and before IBM MQ 9.2.3 for Continuous Delivery.)

[MQ 9.2.3 Jul 2021] [MQ 9.2.0.4 Nov 2021] From IBM MQ 9.2.0 Fix Pack 4 for Long Term Support and IBM MQ 9.2.3 for Continuous Delivery, the IBM MQ managed .NET client has been updated to set SERVERNAME to the respective hostname if the OutboundSNI property is set to HOSTNAME, which allows an IBM MQ managed .NET client to connect to a queue manager using Red Hat OpenShift routes. Note that, in IBM MQ 9.2.0 Fix Pack 4, the OutboundSNI property is added and supported only from the mqclient.ini file; you cannot set the property from the .NET application.

[MQ 9.2.5 Feb 2022] If a client application connects to a queue manager deployed in a Red Hat OpenShift cluster through IBM MQ Internet Pass-Thru (MQIPT), MQIPT can be configured to set the SNI to the hostname by using the SSLClientOutboundSNI property in the route definition.

Example

Client applications that set the SNI to the MQ channel require a new Red Hat OpenShift Route to be created for each channel you wish to connect to. You also have to use unique channel names across your Red Hat OpenShift Container Platform cluster, to allow routing to the correct queue manager.

It is important that MQ channel names do not end in a lower-case letter due to the way IBM MQ maps channel names to SNI headers.

To determine the required host name for each of your new Red Hat OpenShift Routes, you need to map each channel name to an SNI address. See How IBM MQ provides multiple certificates capability for more information.

You must then create a new Red Hat OpenShift Route for each channel, by applying the following yaml in your cluster:

  apiVersion: route.openshift.io/v1
  kind: Route
  metadata:
    name: <provide a unique name for the Route>
    namespace: <the namespace of your MQ deployment>
  spec:
    host: <SNI address mapping for the channel>
    to:
      kind: Service
      name: <the name of the Kubernetes Service for your MQ deployment (for example "<Queue Manager Name>-ibm-mq")>
    port:
      targetPort: 1414
    tls:
      termination: passthrough

Configuring your client application connection details

You can determine the host name to use for your client connection by running the following command:

oc get route <Name of hostname based Route (for example "<Queue Manager Name>-ibm-mq-qm")> 
-n <namespace of your MQ deployment> -o jsonpath="{.spec.host}"

The port for your client connection should be set to the port used by the Red Hat OpenShift Container Platform Router - normally 443.