In part 2 we saw how you can use Heat to quickly deploy Queue Managers with your specific configuration needs using OpenStack’s Heat templates. However, once you have created this Queue Manager how do you quickly share its connection information with client applications? When Queue Managers are deployed dynamically depending on need and if you are unable to predict or control the IP address that will be associated to the Queue Manager, or you have existing Queue Managers outside of OpenStack, the Client Connection definition tables (CCDT) file could be a viable solution for you. In this blog we will explore the CCDT solution using the new MQ v9 feature - CCDT URL.
Before starting this blog, you will need to have completed part 1 (to understand how to create an MQ image) and part 2 (to become familiar with using heat templates to deploy MQ). You should also ensure that you are familar with both MQ CCDT files (what they are and how they are used) and also the new CCDT URL feature. You can get a good summary of both from this blog post.
Additionally, because part 1 created a MQ v8 image you will also need to create a MQ v9 image. The reasons for this is that the CCDT URL feature in MQ Clients is only available in version 9 of MQ. You will need to create a new image that contains the client packages and also uses the MQ 9 drivers, you can use the same steps and scripts as before but you will need to replace the MQ_URL and MQ_PACKAGES variable in the packer script with:
"MQ_URL=http://public.dhe.ibm.com/ibmdl/export/pub/software/websphere/messaging/mqadv/mqadv_dev90_linux_x86-64.tar.gz" "MQ_PACKAGES=\"MQSeriesClient*.rpm MQSeriesSamples*.rpm MQSeriesRuntime-*.rpm MQSeriesServer-*.rpm MQSeriesMsg*.rpm MQSeriesJava*.rpm MQSeriesJRE*.rpm MQSeriesGSKit*.rpm\"
You should also head over to GitHub and download the sample code. The code is split into two folders: Part 1 and Part 2. These folders contain the files you will need for the relevant sections below.
Finally, in this blog I will be using the OpenStack command line tool, you will need to make sure that both the OpenStack client and also the Heat client are installed on your machine. You can install both by using the pip install commands:
pip install python-openstackclient pip install python-heatclient
Part 1 - Setting up the CCDT Host
Before we start registering newly created Queue Managers, we need somewhere to register and host the CCDT file. As the CCDT file is a binary file you have 2 choices for creating, deleting or modifying entries within it: “runmqsc -n” or by using a Queue Manager. In this example we will be using a Queue Manager to create and manage the CCDT file that will be used by a simple python HTTP Server. We will use a single heat stack to create and manage the CCDT server and its required resources, so first you should grab a copy of the following three files and familiarize yourself with what they do:
- CCDT_Setup.yaml – This file is the heat template that we will be using, like the previous files it requires 4 parameters to run but will setup a full OpenStack network and the instance that runs the MQ Queue Manager and HTTP Server.
- CCDT_Setup.mqsc - This file is passed into runmqsc during the creation of the instance to configure the Queue Manager ready for other Queue Managers to connect to it and register their connection details.
- createCCDT.sh – This file is used to create, start and configure the Queue Manager that will manage the CCDT file. It is also used to setup the HTTP Server that will be used to host the file so the clients can obtain connection details
Once you’re happy with the files you should run them in the same way that you created the stack in part 2. Alternatively, you can use the OpenStack client to create the stack instead of the standalone heat client. Either run:
heat stack-create -f ./CCDT_Setup.yaml -P "key_name=my-key;flavor=m1.medium;server_image=ibm-mq;public_net=Public-Network" CCDT
openstack stack create -t ./CCDT_Setup.yaml –-parameter key_name=my-key –-parameter flavor=m1.medium –-parameter server_image=ibm-mq –-parameter public_net=Public-Network CCDT
Once the stack has finished creating you will have a CCDT hosting server which Queue Managers can connect to and register their connection details with. In the next part we will create a Queue Manager and register it with the CCDT server we just created. The HTTP Server on this machine simply hosts the CCDT file that will be retrieved by the MQ v9 clients via a HTTP GET request, in order to make sure that you don't have to keep updating the hosted file, and to make sure you don't host the entire MQ data root, the heat template creates a symlink between the CCDT file and the HTTP hosting directory.
Part 2 – Queue Manager creation and registering
With the CCDT Server up and running we can now create our Queue Manager. Although there are a few possible ways to do the “registering”, in this example we will be using a heat template that does the following:
- Creates and starts a Queue Manager.
- Configures the Queue Manager for client connections.
- Uses ‘runmqsc -c’ to connect to the CCDT Queue Manager to create a Client Connection Channel definition.
Because we are using the client version of runmqsc you must ensure that the MQSeriesClient.rpm package has been installed on the image you use in this section.
To get started you will need to grab the following 4 files and familiarize yourself with them:
- Create_QM.yaml – This is the heat template we will be using, it requires the same 4 parameters as CCDT_Setup.yaml but also requires one extra parameter. The new parameter required is the IP Address of the CCDT Server you created in Part 1, you can obtain this easily by executing “openstack stack output show CCDT CCDT_ip_public” and looking at the value returned in “output_value”.
- createQM.sh – This shell script is used to create, start and configure the Queue Manager before executing runmqsc -c to register with the CCDT Server.
- QM_Setup.mqsc - This file is passed into runmqsc during the creation of the instance to configure the Queue Manager ready for client connections.
- AddCCDT.mqsc – This file is used by the createQM.sh script, it is passed into the runmqsc -c call to register the Queue Manager with the CCDT Server. It has a single MQSC definition and this is the definition to create the Client Connection Channel Definition.
Once you’re happy with the files you should run them in the same way as you ran the previous heat templates. Either run:
heat stack-create -f ./Create_QM.yaml -P "key_name=my-key;flavor=m1.medium;server_image=ibm-mq;public_net=Public-Network; CCDT_ip=126.96.36.199" QM1
openstack stack create -t ./Create_QM.yaml –-parameter key_name=my-key –-parameter flavor=m1.medium –-parameter server_image=ibm-mq –-parameter public_net=Public-Network –-parameter CCDT_ip=188.8.131.52 QM1
Once the stack has completed you should check the logs to make sure that the Queue Manager has been created and you can see the runmqsc -c connection creating the Client connection channel. Provided both of those tasks have completed successfully then MQ v9 client applications will be able to connect to the Queue manager using the new CCDT URL feature. In the next (and final) section we will show an example of how you can use the MQ sample applications to test this.
Part 3 – Using the hosted CCDT in client applications
To test the CCDT hosting server we will be using the sample programs “amqsputc” and “amqsgetc”. These are available with the MQ installation so long as you installed the MQSeriesSamples.rpm package; as these are client applications you also need to ensure you have installed the MQSeriesClient.rpm package.
First create an instance on a network that can access both the CCDT Server and the Queue Manager, you can do this either by hand using the GUI or command line or create a heat template to automate it for you. Once the instance has created log onto the instance and change to the mqm user before navigating to the following directory “/opt/mqm/samp/bin” (This assumes that MQ has been installed in a default location).
If you look in this directory you should see several sample applications ready to be executed including the two we are going to run. Before you run them though, you need to set an environment variable to tell the application where it needs to get the CCDT file from. Execute the following, replacing <CCDT IP> with the IP address of your CCDT Server:
export MQCCDTURL=http://<CCDT IP>:80/AMQCLCHL.TAB
This environment variable is recognised by MQ Clients to alert them to use the CCDT file located in this location. It is important that you do not forget the http:// at the front as this is required to tell MQ how to obtain the file. If you do not specify it then MQ will attempt to obtain the file locally, instead of via HTTP. Once the environment variable is set we can use amqsputc to put messages to the Queue on the Queue Manager we created in section 2. Execute the following and place a few messages onto the queue before hitting return/enter twice to quit out of the program:
./amqsputc LOCAL.QUEUE QM1
Before you retrieve the messages you can prove to yourself that they really do exist on the Queue manager by logging into its box and querying the CURDEPTH of the local Queue to make sure it shows the number of messages you put. When you are ready to retrieve the messages you can execute the following:
./amqsgetc LOCAL.QUEUE QM1
This blog post focused on a possible concept of tackling passing Queue Manager connection information to a Client application using existing features. As a concept it should be modified and adapted to meet your requirements but can be used as a starting point.