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

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

About this task

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 Server Name Indication (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. Possible values are OutboundSNI=CHANNEL (the default value) or OutboundSNI=HOSTNAME. For more information, see SSL stanza of the client configuration file. Note that CHANNEL and HOSTNAME are the exact values that you use; they are not variable names that you replace with an actual channel name or host 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.)

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.

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.

OutboundSNI, multiple certificates, and Red Hat OpenShift routes: IBM MQ uses the SNI header to provide multiple certificates functionality. If an application is connecting to an IBM MQ channel that is configured to use a different certificate through the CERTLABL field, then the application must connect with an OutboundSNI setting of CHANNEL.; If your Red Hat OpenShift Route configuration requires a HOSTNAME SNI then you are unable to use the multiple certificates functionality of IBM MQ and unable to set a CERTLABL setting on any IBM MQ channel object.; If an application with an OutboundSNI setting of anything other than CHANNEL connects to a channel with a certificate label configured, the application is rejected with an MQRC_SSL_INITIALIZATION_ERROR, and an AMQ9673 message is printed in the queue manager error logs.; For more information on how IBM MQ provides multiple certificate functionality, see How IBM MQ provides multiple certificates capability .

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.