Instana monitoring: Configuring the queue manager

Set up a queue manager that uses TLS to communicate with the IBM® Instana® agent on the Red Hat® OpenShift® Container Platform. The authentication for this connection is done using an SSLPEERMAP.

Before you begin

Important: Integration with IBM Instana tracing is supported only on the Red Hat OpenShift Container Platform.

This task assumes that you have configured the agents for IBM Instana monitoring.

Procedure

Configure the queue manager through both MQSC and INI.

MQSC is used to set up a new TLS enabled channel, and then configure that channel to authenticate the connecting IBM Instana agent if it has a certificate with the required fields. In this case, we map any connecting client with a certificate containing the fields CN=instana-agent,OU=app team1 to user app1. MQSC then grants permission for user app1 to perform the required operations for IBM Instana monitoring.

The INI file is used to grant permissions to our external user app1.

The following configmap contains the required MQSC and INI settings. Deploy it into your queue manager namespace.

apiVersion: v1
data:
  channel.mqsc: |-
    DEFINE CHANNEL('INSTANA.A.SVRCONN') CHLTYPE(SVRCONN) SSLCAUTH(REQUIRED) SSLCIPH('ANY_TLS12_OR_HIGHER')
    ALTER QMGR CONNAUTH(' ')
    REFRESH SECURITY
    SET CHLAUTH('INSTANA.A.SVRCONN') TYPE(SSLPEERMAP) SSLPEER('CN=*') USERSRC(NOACCESS) ACTION(REPLACE)
    SET CHLAUTH('*') TYPE(ADDRESSMAP) ADDRESS('*') USERSRC(NOACCESS) ACTION(REPLACE)
    SET CHLAUTH('INSTANA.A.SVRCONN') TYPE(SSLPEERMAP) SSLPEER('CN=instana-agent,OU=app team1') USERSRC(MAP) MCAUSER('app1')
    SET AUTHREC PRINCIPAL('app1') OBJTYPE(QMGR) AUTHADD(ALL)
    SET AUTHREC PROFILE('SYSTEM.ADMIN.COMMAND.QUEUE') PRINCIPAL('app1') OBJTYPE(QUEUE) AUTHADD(PUT,INQ,DSP,CHG)
    SET AUTHREC PROFILE('SYSTEM.**') PRINCIPAL('app1') OBJTYPE(TOPIC) AUTHADD(DSP)
    SET AUTHREC PROFILE('*') PRINCIPAL('app1') OBJTYPE(TOPIC) AUTHADD(DSP)
    SET AUTHREC PROFILE('SYSTEM.**') PRINCIPAL('app1') OBJTYPE(QUEUE) AUTHADD(DSP, CHG, GET)
    SET AUTHREC PROFILE('SYSTEM.**') PRINCIPAL('app1') OBJTYPE(LISTENER) AUTHADD(DSP)
    SET AUTHREC PROFILE('AMQ.*') PRINCIPAL('app1') OBJTYPE(QUEUE) AUTHADD(DSP, CHG)
    REFRESH SECURITY TYPE(CONNAUTH)
  auth.ini: |-
    Service:
      Name=AuthorizationService
      EntryPoints=14
      SecurityPolicy=UserExternal
kind: ConfigMap
metadata:
  namespace: your-queue-manager-namespace
  name: qmgr-monitoring-config

where your-queue-manager-namespace is the namespace in which your queue manager will be deployed.

Note: If you are monitoring user-defined queues then you must add additional lines to the configmap MQSC, granting DSP, CHG and GET permissions to those queues. For example:

SET AUTHREC PROFILE('MYQUEUE') PRINCIPAL('app1') OBJTYPE(QUEUE) AUTHADD(DSP, CHG, GET).

This example uses a configmap for the MQSC and INI data, but you can use a secret if any additions you make are confidential. For general information regarding deploying with MQSC and INI, see Example: Supplying MQSC and INI files.

For a TLS connection to be made, the queue manager must trust the certificate of the IBM Instana agent. To achieve this, create a secret containing just the certificate of the IBM Instana agent:
```
oc create secret generic instana-certificate-secret --from-file=./application.crt -n your-queue-manager-namespace
```
The queue manager must present its own certificate for the TLS handshake, and requires access to the associated private key. Deploy a secret containing the key and certificate that you either created earlier or already possess:
```
oc create secret tls qm-tls-secret --cert server.crt --key server.key -n your-queue-manager-namespace
```
With the configmap and secret created, you are ready to create the queue manager itself.
Ensure that your queue manager YAML does not set the environment variable MQSNOAUT in the queue manager container.
Otherwise, after it is enabled, the authentication mechanism will not work. Removing the variable after deployment does not cause the mechanism to be re-enabled, and the queue manager has to be recreated.
Add the following sections to your queue manager definition, where MYQM is the name of your queue manager:
```
spec:
  queueManager:
    name: MYQM   #(a)
    ini:   #(b)
      - configMap:
          items:
            - auth.ini
          name: qmgr-monitoring-config
    mqsc:   #(c)
      - configMap:
          items:
            - channel.mqsc
          name: qmgr-monitoring-config
  pki:
    keys:   #(d)
        - name: default
          secret:
            items:
            - tls.key
            - tls.crt
            secretName: qm-tls-secret
    trust:   #(e)
      - name: app
        secret:
          items:
            - application.crt
          secretName: instana-certificate-secret
```
The flagged sections of the specification are described as follows:
1. Ensure that you have given your underlying queue manager a unique name. If the underlying queue manager does not have a unique name, then monitoring might not work as intended. This name must match the name in the IBM Instana agent configmap that was edited earlier.
2. The INI information that was written to the configmap is added to the queue manager.
3. The MQSC information that was written to the configmap is added to the queue manager.
4. The queue manager certificate and private key are added to the queue manager keystore.
5. The IBM Instana agent certificate is added to the queue manager trust store.
Optional: Enable IBM Instana Tracing on your monitored queue manager.

If you want to do this, see Integrating IBM MQ with IBM Instana tracing.
Deploy the queue manager.

What to do next

You are now ready to verify and debug the IBM Instana monitoring.