We’re pleased to announce the availability of a technical preview of a Chef cookbook for IBM MQ. The source code for this image is available on GitHub. The cookbook is currently fairly basic, but allows you to install MQ, as well as create and start queue managers.
This blog entry takes you through the steps of creating your own Chef recipe to install MQ, and testing it in a local VM.
Update: A video of these steps is also now available.
You will need to install the Chef Developer Kit and Vagrant to follow these instructions.
Writing a recipe to install MQ
The first step is to create a new Chef cookbook:
chef generate cookbook mymq
This new cookbook will use the IBM MQ cookbook, so you need to add that as a dependency. When running Chef on Ubuntu, it's also recommended to use the `apt` cookbook, to make sure the apt package list gets updated properly. Add the following line to the end of `metadata.rb`:
You need to tell your dependency management tool how to find the "ibm_mq" cookbook. The Chef Developer Kit uses Berkshelf for this, so you need to append the following line to your `Berksfile`:
cookbook 'ibm_mq', github: "ibm-messaging/mq-chef", tag: "v0.1.1"
Now you can write a new recipe to configure MQ, by editing `recipes/default.rb`:
ibm_mq_installation 'Installation1' do
ibm_mq_queue_manager 'qm1' do
action [:create, :start]
execute 'runmqsc' do
command "echo 'define qlocal(foo) replace' | runmqsc qm1"
The first part says that you want to use the `ibm_mq_installation` resource. No action is specified for this resource, so the default action of `:create` will be used, which will install MQ. There are two resource properties used here:
- The `source` property indicates a remote URI where an IBM MQ for Linux install package is available, in "tar.gz" format. You'll probably want to change this property to point to a local file server where you can download MQ from.
- The `accept_license` property is used to indicate that you accept the terms of the IBM license associated with the install package.
- The `primary` property is used to indicate that this is the primary installation of MQ. Note that at the time of writing, non-primary installations are not allowed.
Other resource properties are available as well, for example you could use the following:
ibm_mq_installation 'Installation1' do
packages %w(MQSeriesServer MQSeriesGSKit MQSeriesSamples MQSeriesClient)
This will install the MQ server and client, including GSKit and the samples, plus any dependent packages. You can see the full list of available resources and properties in the documentation.
The second part of the recipe uses the `ibm_mq_queue_manager` resource to create and start a queue manager called "qm1".
The third and final part of the recipe uses the Chef `execute` resource to invoke the `runmqsc` command to define an MQ queue. Note the use of the MQSC `replace` keyword: this is important so that multiple Chef runs of the same cookbook can succeed. If you have a lot of MQSC commands to run, you might want to use the Chef `file` or `template` resources.
That's it for the Chef part! In order to test out the new cookbook, you can use the Test Kitchen tool, which is included with the Chef Developer Kit. When you generated the initial cookbook, a file called `.kitchen.yml` was created, which you can edit to contain the following:
- name: ubuntu-14.04
- name: client
This file tells Test Kitchen that you want to test your cookbook using a Vagrant virtual machine with Ubuntu 14.04, using Chef Zero, and running the "apt" cookbook's default recipe, and the default recipe from the "mymq" cookbook.
You can run Test Kitchen as follows:
chef exec kitchen converge
This will create a new virtual machine for you, install the Chef client, install your cookbook and all the cookbooks it depends on, then run the Chef client. After it's finished, you can log into the virtual machine as follows:
chef exec kitchen login
You can manually verify that MQ is correctly installed and working using the `dspmq` command. See the Test Kitchen documentation for information on how to write automated tests.
The current cookbook is fairly basic, but we hope that you will find it useful. We'd love to hear from you if you do! If you have have any requests, ideas for future features, or have any trouble getting it working, please let us know - you can either add a comment here, or you can raise an issue on GitHub.